summaryrefslogtreecommitdiff
path: root/Documentation/pretty-formats.txt
AgeCommit message (Collapse)AuthorFilesLines
2020-12-09pretty format %(trailers): add a "key_value_separator"Libravatar Ævar Arnfjörð Bjarmason1-0/+4
Add a "key_value_separator" option to the "%(trailers)" pretty format, to go along with the existing "separator" argument. In combination these two options make it trivial to produce machine-readable (e.g. \0 and \0\0-delimited) format output. As elaborated on in a previous commit which added "keyonly" it was needlessly tedious to extract structured data from "%(trailers)" before the addition of this "key_value_separator" option. As seen by the test being added here extracting this data now becomes trivial. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-12-09pretty format %(trailers): add a "keyonly"Libravatar Ævar Arnfjörð Bjarmason1-2/+2
Add support for a "keyonly". This allows for easier parsing out of the key and value. Before if you didn't want to make assumptions about how the key was formatted. You'd need to parse it out as e.g.: --pretty=format:'%H%x00%(trailers:separator=%x00%x00)' \ '%x00%(trailers:separator=%x00%x00,valueonly)' And then proceed to deduce keys by looking at those two and subtracting the value plus the hardcoded ": " separator from the non-valueonly %(trailers) line. Now it's possible to simply do: --pretty=format:'%H%x00%(trailers:separator=%x00%x00,keyonly)' \ '%x00%(trailers:separator=%x00%x00,valueonly)' Which at least reduces it to a state machine where you get N keys and correlate them with N values. Even better would be to have a way to change the ": " delimiter to something easily machine-readable (a key might contain ": " too). A follow-up change will add support for that. I don't really have a use-case for just "keyonly" myself. I suppose it would be useful in some cases as "key=*" matches case-insensitively, so a plain "keyonly" will give you the variants of the keys you matched. I'm mainly adding it to fix the inconsistency with "valueonly". Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-12-09pretty format %(trailers) doc: avoid repetitionLibravatar Ævar Arnfjörð Bjarmason1-14/+16
Change the documentation for the various %(trailers) options so it isn't repeating part of the documentation for "only" about how boolean values are handled. Instead, let's split the description of that into general documentation at the top. It then suffices to refer to it by listing the options as "opt[=<BOOL>]". I'm also changing it to upper-case "[=<BOOL>]" from "[=val]" for consistency with "<SEP>" It took me a couple of readings to realize that these options were referring back to the "only" option's treatment of boolean values. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-07-06Merge branch 'mk/pb-pretty-email-without-domain-part-fix'Libravatar Junio C Hamano1-2/+2
Docfix. * mk/pb-pretty-email-without-domain-part-fix: doc: fix author vs. committer copy/paste error
2020-06-23doc: fix author vs. committer copy/paste errorLibravatar Miroslav Koškár1-2/+2
Signed-off-by: Miroslav Koškár <mk@mkoskar.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-04-15Documentation: explain "mboxrd" pretty formatLibravatar Emma Brooks1-0/+6
The "mboxrd" pretty format was introduced in 9f23e04061 (pretty: support "mboxrd" output format, 2016-06-05) but wasn't mentioned in the documentation. Signed-off-by: Emma Brooks <me@pluvano.com> Acked-by: Eric Wong <e@80x24.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-30Merge branch 'hi/gpg-mintrustlevel'Libravatar Junio C Hamano1-0/+1
gpg.minTrustLevel configuration variable has been introduced to tell various signature verification codepaths the required minimum trust level. * hi/gpg-mintrustlevel: gpg-interface: add minTrustLevel as a configuration option
2020-01-15gpg-interface: add minTrustLevel as a configuration optionLibravatar Hans Jerry Illikainen1-0/+1
Previously, signature verification for merge and pull operations checked if the key had a trust-level of either TRUST_NEVER or TRUST_UNDEFINED in verify_merge_signature(). If that was the case, the process die()d. The other code paths that did signature verification relied entirely on the return code from check_commit_signature(). And signatures made with a good key, irregardless of its trust level, was considered valid by check_commit_signature(). This difference in behavior might induce users to erroneously assume that the trust level of a key in their keyring is always considered by Git, even for operations where it is not (e.g. during a verify-commit or verify-tag). The way it worked was by gpg-interface.c storing the result from the key/signature status *and* the lowest-two trust levels in the `result` member of the signature_check structure (the last of these status lines that were encountered got written to `result`). These are documented in GPG under the subsection `General status codes` and `Key related`, respectively [1]. The GPG documentation says the following on the TRUST_ status codes [1]: """ These are several similar status codes: - TRUST_UNDEFINED <error_token> - TRUST_NEVER <error_token> - TRUST_MARGINAL [0 [<validation_model>]] - TRUST_FULLY [0 [<validation_model>]] - TRUST_ULTIMATE [0 [<validation_model>]] For good signatures one of these status lines are emitted to indicate the validity of the key used to create the signature. The error token values are currently only emitted by gpgsm. """ My interpretation is that the trust level is conceptionally different from the validity of the key and/or signature. That seems to also have been the assumption of the old code in check_signature() where a result of 'G' (as in GOODSIG) and 'U' (as in TRUST_NEVER or TRUST_UNDEFINED) were both considered a success. The two cases where a result of 'U' had special meaning were in verify_merge_signature() (where this caused git to die()) and in format_commit_one() (where it affected the output of the %G? format specifier). I think it makes sense to refactor the processing of TRUST_ status lines such that users can configure a minimum trust level that is enforced globally, rather than have individual parts of git (e.g. merge) do it themselves (except for a grace period with backward compatibility). I also think it makes sense to not store the trust level in the same struct member as the key/signature status. While the presence of a TRUST_ status code does imply that the signature is good (see the first paragraph in the included snippet above), as far as I can tell, the order of the status lines from GPG isn't well-defined; thus it would seem plausible that the trust level could be overwritten with the key/signature status if they were stored in the same member of the signature_check structure. This patch introduces a new configuration option: gpg.minTrustLevel. It consolidates trust-level verification to gpg-interface.c and adds a new `trust_level` member to the signature_check structure. Backward-compatibility is maintained by introducing a special case in verify_merge_signature() such that if no user-configurable gpg.minTrustLevel is set, then the old behavior of rejecting TRUST_UNDEFINED and TRUST_NEVER is enforced. If, on the other hand, gpg.minTrustLevel is set, then that value overrides the old behavior. Similarly, the %G? format specifier will continue show 'U' for signatures made with a key that has a trust level of TRUST_UNDEFINED or TRUST_NEVER, even though the 'U' character no longer exist in the `result` member of the signature_check structure. A new format specifier, %GT, is also introduced for users that want to show all possible trust levels for a signature. Another approach would have been to simply drop the trust-level requirement in verify_merge_signature(). This would also have made the behavior consistent with other parts of git that perform signature verification. However, requiring a minimum trust level for signing keys does seem to have a real-world use-case. For example, the build system used by the Qubes OS project currently parses the raw output from verify-tag in order to assert a minimum trust level for keys used to sign git tags [2]. [1] https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=doc/doc/DETAILS;h=bd00006e933ac56719b1edd2478ecd79273eae72;hb=refs/heads/master [2] https://github.com/QubesOS/qubes-builder/blob/9674c1991deef45b1a1b1c71fddfab14ba50dccf/scripts/verify-git-tag#L43 Signed-off-by: Hans Jerry Illikainen <hji@dyntopia.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-12-10Merge branch 'dl/pretty-reference'Libravatar Junio C Hamano1-8/+21
"git log" family learned "--pretty=reference" that gives the name of a commit in the format that is often used to refer to it in log messages. * dl/pretty-reference: SubmittingPatches: use `--pretty=reference` pretty: implement 'reference' format pretty: add struct cmt_fmt_map::default_date_mode_type pretty: provide short date format t4205: cover `git log --reflog -z` blindspot pretty.c: inline initalize format_context revision: make get_revision_mark() return const pointer completion: complete `tformat:` pretty format SubmittingPatches: remove dq from commit reference pretty-formats.txt: use generic terms for hash SubmittingPatches: use generic terms for hash
2019-11-20pretty: implement 'reference' formatLibravatar Denton Liu1-0/+11
The standard format for referencing other commits within some projects (such as git.git) is the reference format. This is described in Documentation/SubmittingPatches as If you want to reference a previous commit in the history of a stable branch, use the format "abbreviated hash (subject, date)", like this: .... Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30) noticed that ... .... Since this format is so commonly used, standardize it as a pretty format. The tests that are implemented essentially show that the format-string does not change in response to various log options. This is useful because, for future developers, it shows that we've considered the limitations of the "canned format-string" approach and we are fine with them. Based-on-a-patch-by: SZEDER Gábor <szeder.dev@gmail.com> Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-11-20pretty: provide short date formatLibravatar René Scharfe1-0/+2
Add the placeholders %as and %cs to format author date and committer date, respectively, without the time part, like --date=short does, i.e. like YYYY-MM-DD. Signed-off-by: René Scharfe <l.s.r@web.de> Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-11-20pretty-formats.txt: use generic terms for hashLibravatar Denton Liu1-8/+8
Since Git is planning on upgrading from SHA-1 to be more hash-agnostic, replace specific references to SHA-1 with more generic terminology. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-10-30pretty: add "%aL" etc. to show local-part of email addressesLibravatar Prarit Bhargava1-0/+6
In many projects the number of contributors is low enough that users know each other and the full email address doesn't need to be displayed. Displaying only the author's username saves a lot of columns on the screen. Existing 'e/E' (as in "%ae" and "%aE") placeholders would show the author's address as "prarit@redhat.com", which would waste columns to show the same domain-part for all contributors when used in a project internal to redhat. Introduce 'l/L' placeholders that strip '@' and domain part from the e-mail address. Signed-off-by: Prarit Bhargava <prarit@redhat.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-09-12doc: minor formatting fixLibravatar Cameron Steffen1-1/+1
Move a closing backtick that was placed one character too soon. Signed-off-by: Cameron Steffen <cam.steffen94@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-07Merge branch 'aw/pretty-trailers'Libravatar Junio C Hamano1-112/+152
The %(trailers) formatter in "git log --format=..." now allows to optionally pick trailers selectively by keyword, show only values, etc. * aw/pretty-trailers: pretty: add support for separator option in %(trailers) strbuf: separate callback for strbuf_expand:ing literals pretty: add support for "valueonly" option in %(trailers) pretty: allow showing specific trailers pretty: single return path in %(trailers) handling pretty: allow %(trailers) options with explicit value doc: group pretty-format.txt placeholders descriptions
2019-02-08Merge branch 'kl/pretty-doc-markup-fix'Libravatar Junio C Hamano1-1/+1
Doc update. * kl/pretty-doc-markup-fix: doc: prevent overflowing <code> tag in rendered HTML
2019-02-07doc: prevent overflowing <code> tag in rendered HTMLLibravatar Katrin Leinweber1-1/+1
Add an apparently missing back-tick to fix a multi-line <code> section on https://git-scm.com/docs/git-log which seems to have been caused by commit 18fb7ffc ("pretty: respect color settings [...]", 2017-07-13). Signed-off-by: Katrin Leinweber <katrin.leinweber@uni-konstanz.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-01-29pretty: add support for separator option in %(trailers)Libravatar Anders Waldenborg1-0/+9
By default trailer lines are terminated by linebreaks ('\n'). By specifying the new 'separator' option they will instead be separated by user provided string and have separator semantics rather than terminator semantics. The separator string can contain the literal formatting codes %n and %xNN allowing it to be things that are otherwise hard to type such as %x00, or comma and end-parenthesis which would break parsing. E.g: $ git log --pretty='%(trailers:key=Reviewed-by,valueonly,separator=%x00)' Signed-off-by: Anders Waldenborg <anders@0x63.nu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-01-29pretty: add support for "valueonly" option in %(trailers)Libravatar Anders Waldenborg1-0/+2
With the new "key=" option to %(trailers) it often makes little sense to show the key, as it by definition already is knows which trailer is printed there. This new "valueonly" option makes it omit the key when printing trailers. E.g.: $ git show -s --pretty='%s%n%(trailers:key=Signed-off-by,valueonly)' aaaa88182 will show: > upload-pack: fix broken if/else chain in config callback > Jeff King <peff@peff.net> > Junio C Hamano <gitster@pobox.com> Signed-off-by: Anders Waldenborg <anders@0x63.nu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-01-29pretty: allow showing specific trailersLibravatar Anders Waldenborg1-0/+8
Adds a new "key=X" option to "%(trailers)" which will cause it to only print trailer lines which match any of the specified keys. Signed-off-by: Anders Waldenborg <anders@0x63.nu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-01-29pretty: allow %(trailers) options with explicit valueLibravatar Anders Waldenborg1-4/+10
In addition to old %(trailers:only) it is now allowed to write %(trailers:only=yes) By itself this only gives (the not quite so useful) possibility to have users change their mind in the middle of a formatting string (%(trailers:only=true,only=false)). However, it gives users the opportunity to override defaults from future options. Signed-off-by: Anders Waldenborg <anders@0x63.nu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-01-11log: add %S option (like --source) to log --formatLibravatar Issac Trotts1-0/+2
Make it possible to write for example git log --format="%H,%S" where the %S at the end is a new placeholder that prints out the ref (tag/branch) for each commit. Using %d might seem like an alternative but it only shows the ref for the last commit in the branch. Signed-off-by: Issac Trotts <issactrotts@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-12-09doc: group pretty-format.txt placeholders descriptionsLibravatar Anders Waldenborg1-110/+125
The placeholders can be grouped into three kinds: * literals * affecting formatting of later placeholders * expanding to information in commit Also change the list to a definition list (using '::') Signed-off-by: Anders Waldenborg <anders@0x63.nu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-10-23gpg-interface.c: obtain primary key fingerprint as wellLibravatar Michał Górny1-0/+2
Obtain the primary key fingerprint off VALIDSIG status message, and expose it via %GP format. Signed-off-by: Michał Górny <mgorny@gentoo.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-10-23gpg-interface.c: support getting key fingerprint via %GF formatLibravatar Michał Górny1-0/+1
Support processing VALIDSIG status that provides additional information for valid signatures. Use this information to propagate signing key fingerprint and expose it via %GF pretty format. This format can be used to build safer key verification systems that verify the key via complete fingerprint rather than short/long identifier provided by %GK. Signed-off-by: Michał Górny <mgorny@gentoo.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-03-08Merge branch 'mk/doc-pretty-fill'Libravatar Junio C Hamano1-1/+1
Docfix. * mk/doc-pretty-fill: docs/pretty-formats: fix typo '% <(<N>)' -> '%<|(<N>)'
2018-02-27docs/pretty-formats: fix typo '% <(<N>)' -> '%<|(<N>)'Libravatar Mårten Kongstad1-1/+1
Remove erroneous space between % and < in '% <(<N>)'. Signed-off-by: Mårten Kongstad <marten.kongstad@gmail.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-12-08docs/pretty-formats: mention commas in %(trailers) syntaxLibravatar Jeff King1-5/+7
Commit 84ff053d47 (pretty.c: delimit "%(trailers)" arguments with ",", 2017-10-01) switched the syntax of the trailers placeholder, but forgot to update the documentation in pretty-formats.txt. There's no need to mention the old syntax; it was never in a released version of Git. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-08-26Merge branch 'jk/trailers-parse'Libravatar Junio C Hamano1-1/+4
"git interpret-trailers" has been taught a "--parse" and a few other options to make it easier for scripts to grab existing trailer lines from a commit log message. * jk/trailers-parse: doc/interpret-trailers: fix "the this" typo pretty: support normalization options for %(trailers) t4205: refactor %(trailers) tests pretty: move trailer formatting to trailer.c interpret-trailers: add --parse convenience option interpret-trailers: add an option to unfold values interpret-trailers: add an option to show only existing trailers interpret-trailers: add an option to show only the trailers trailer: put process_trailers() options into a struct
2017-08-15pretty: support normalization options for %(trailers)Libravatar Jeff King1-1/+4
The interpret-trailers command recently learned some options to make its output easier to parse (for a caller whose only interested in picking out the trailer values). But it's not very efficient for asking for the trailers of many commits in a single invocation. We already have "%(trailers)" to do that, but it doesn't know about unfolding or omitting non-trailers. Let's plumb those options through, so you can have the best of both. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-07-13pretty: respect color settings for %C placeholdersLibravatar Jeff King1-7/+11
The color placeholders have traditionally been unconditional, showing colors even when git is not otherwise configured to do so. This was not so bad for their original use, which was on the command-line (and the user could decide at that moment whether to add colors or not). But these days we have configured formats via pretty.*, and those should operate correctly in multiple contexts. In 3082517 (log --format: teach %C(auto,black) to respect color config, 2012-12-17), we gave an extended placeholder that could be used to accomplish this. But it's rather clunky to use, because you have to specify it individually for each color (and their matching resets) in the format. We shied away from just switching the default to auto, because it is technically breaking backwards compatibility. However, there's not really a use case for unconditional colors. The most plausible reason you would want them is to redirect "git log" output to a file. But there, the right answer is --color=always, as it does the right thing both with custom user-format colors and git-generated colors. So let's switch to the more useful default. In the off-chance that somebody really does find a use for unconditional colors without wanting to enable the rest of git's colors, we provide a new %C(always,...) to enable the old behavior. And we can remind them of --color=always in the documentation. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-07-10Merge branch 'ah/doc-pretty-color-auto-prefix' into maintLibravatar Junio C Hamano1-5/+6
Doc update. * ah/doc-pretty-color-auto-prefix: doc: clarify syntax for %C(auto,...) in pretty formats
2017-06-30Merge branch 'ah/doc-pretty-color-auto-prefix'Libravatar Junio C Hamano1-5/+6
Doc update. * ah/doc-pretty-color-auto-prefix: doc: clarify syntax for %C(auto,...) in pretty formats
2017-06-24Merge branch 'sg/doc-pretty-formats' into maintLibravatar Junio C Hamano1-2/+2
Doc update. * sg/doc-pretty-formats: docs/pretty-formats: stress that %- removes all preceding line-feeds
2017-06-24Merge branch 'sg/doc-pretty-formats'Libravatar Junio C Hamano1-2/+2
Doc update. * sg/doc-pretty-formats: docs/pretty-formats: stress that %- removes all preceding line-feeds
2017-06-24doc: clarify syntax for %C(auto,...) in pretty formatsLibravatar Andreas Heiduk1-5/+6
The manual correctly describes the syntax with `auto,` but the trailing `,` is hard to spot in a terminal. The HTML format does not have this problem. Adding an example helps both worlds. Signed-off-by: Andreas Heiduk <asheiduk@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-06-15docs/pretty-formats: stress that %- removes all preceding line-feedsLibravatar SZEDER Gábor1-2/+2
Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-05-23Documentation: fix formatting typo in pretty-formats.txtLibravatar Andreas Heiduk1-1/+1
A missing space messed up formatting of the `%(trailers)` format. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-12-11pretty: add %(trailers) format for displaying trailers of a commit messageLibravatar Jacob Keller1-0/+2
Recent patches have expanded on the trailers.c code and we have the builtin commant git-interpret-trailers which can be used to add or modify trailer lines. However, there is no easy way to simply display the trailers of a commit message. Add support for %(trailers) format modifier which will use the trailer_info_get() calls to read trailers in an identical way as git interpret-trailers does. Use a long format option instead of a short name so that future work can more easily unify ref-filter and pretty formats. Add documentation and tests for the same. Signed-off-by: Jacob Keller <jacob.keller@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-10-28Merge branch 'rs/pretty-format-color-doc-fix' into maintLibravatar Junio C Hamano1-1/+2
Small doc update. * rs/pretty-format-color-doc-fix: pretty: fix document link for color specification
2016-10-26Merge branch 'mg/gpg-richer-status'Libravatar Junio C Hamano1-2/+8
The GPG verification status shown in "%G?" pretty format specifier was not rich enough to differentiate a signature made by an expired key, a signature made by a revoked key, etc. New output letters have been assigned to express them. * mg/gpg-richer-status: gpg-interface: use more status letters
2016-10-17Merge branch 'rs/pretty-format-color-doc-fix'Libravatar Junio C Hamano1-1/+2
* rs/pretty-format-color-doc-fix: pretty: fix document link for color specification
2016-10-12gpg-interface: use more status lettersLibravatar Michael J Gruber1-2/+8
According to gpg2's doc/DETAILS: For each signature only one of the codes GOODSIG, BADSIG, EXPSIG, EXPKEYSIG, REVKEYSIG or ERRSIG will be emitted. gpg1 ("classic") behaves the same (although doc/DETAILS differs). Currently, we parse gpg's status output for GOODSIG, BADSIG and trust information and translate that into status codes G, B, U, N for the %G? format specifier. git-verify-* returns success in the GOODSIG case only. This is somewhat in disagreement with gpg, which considers the first 5 of the 6 above as VALIDSIG, but we err on the very safe side. Introduce additional status codes E, X, Y, R for ERRSIG, EXPSIG, EXPKEYSIG, and REVKEYSIG so that a user of %G? gets more information about the absence of a 'G' on first glance. Requested-by: Alex <agrambot@gmail.com> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-10-11pretty: fix document link for color specificationLibravatar René Scharfe1-1/+2
Helped-by: Jeff King <peff@peff.net> Signed-off-by: Rene Scharfe <l.s.r@web.de> Reviewed-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-09-19Merge branch 'po/range-doc' into maintLibravatar Junio C Hamano1-1/+1
Clarify various ways to specify the "revision ranges" in the documentation. * po/range-doc: doc: revisions: sort examples and fix alignment of the unchanged doc: revisions: show revision expansion in examples doc: revisions - clarify reachability examples doc: revisions - define `reachable` doc: gitrevisions - clarify 'latter case' is revision walk doc: gitrevisions - use 'reachable' in page description doc: revisions: single vs multi-parent notation comparison doc: revisions: extra clarification of <rev>^! notation effects doc: revisions: give headings for the two and three dot notations doc: show the actual left, right, and boundary marks doc: revisions - name the left and right sides doc: use 'symmetric difference' consistently
2016-09-08Merge branch 'po/range-doc'Libravatar Junio C Hamano1-1/+1
Clarify various ways to specify the "revision ranges" in the documentation. * po/range-doc: doc: revisions: sort examples and fix alignment of the unchanged doc: revisions: show revision expansion in examples doc: revisions - clarify reachability examples doc: revisions - define `reachable` doc: gitrevisions - clarify 'latter case' is revision walk doc: gitrevisions - use 'reachable' in page description doc: revisions: single vs multi-parent notation comparison doc: revisions: extra clarification of <rev>^! notation effects doc: revisions: give headings for the two and three dot notations doc: show the actual left, right, and boundary marks doc: revisions - name the left and right sides doc: use 'symmetric difference' consistently
2016-07-22doc/pretty-formats: explain shortening of %gdLibravatar Jeff King1-3/+6
The actual shortening rules aren't that interesting and probably not worth getting into (I gloss over them here as "shortened for human readability"). But the fact that %gD shows whatever you gave on the command line is subtle and worth mentioning. Since most people will feed a shortened refname in the first place, it otherwise makes it hard to understand the difference between the two. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-07-22doc/pretty-formats: describe index/time formats for %gdLibravatar Jeff King1-2/+5
The "reflog selector" format changes based on a series of heuristics, and that applies equally to both stock "log -g" output, as well as "--format=%gd". The documentation for "%gd" doesn't cover this. Let's mention the multiple formats and refer the user back to the "-g" section for the complete rules. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-07-20doc: show the actual left, right, and boundary marksLibravatar Philip Oakley1-1/+1
Signed-off-by: Philip Oakley <philipoakley@iee.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-05-13Documentation: clarify signature verificationLibravatar Keller Fuchs1-2/+2
Clarify that "merge --verify-signatures" checks the signature on the tip commit of the history being merged. Uniformise the vocabulary used wrt. key/signature validity with OpenPGP: - a signature is valid if made by a key with a valid uid; - in the default trust-model, a uid is valid if signed by a trusted key; - a key is trusted if the (local) user set a trust level for it. Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Keller Fuchs <KellerFuchs@hashbang.sh> Signed-off-by: Junio C Hamano <gitster@pobox.com>