git/Documentation, branch v2.25.2

Git 2.25.2

2020-03-17T22:06:37Z

Signed-off-by: Junio C Hamano

Merge branch 'jk/doc-credential-helper' into maint

2020-03-17T22:02:26Z

Docfix. * jk/doc-credential-helper: doc: move credential helper info into gitcredentials(7)

Merge branch 'jc/doc-single-h-is-for-help' into maint

2020-03-17T22:02:24Z

Both "git ls-remote -h" and "git grep -h" give short usage help, like any other Git subcommand, but it is not unreasonable to expect that the former would behave the same as "git ls-remote --head" (there is no other sensible behaviour for the latter). The documentation has been updated in an attempt to clarify this. * jc/doc-single-h-is-for-help: Documentation: clarify that `-h` alone stands for `help`

Merge branch 'en/check-ignore' into maint

2020-03-17T22:02:23Z

"git check-ignore" did not work when the given path is explicitly marked as not ignored with a negative entry in the .gitignore file. * en/check-ignore: check-ignore: fix documentation and implementation to match

Merge branch 'jk/push-option-doc-markup-fix' into maint

2020-03-17T22:02:22Z

Doc markup fix. * jk/push-option-doc-markup-fix: doc/config/push: use longer "--" line for preformatted example

Merge branch 'jk/doc-diff-parallel' into maint

2020-03-17T22:02:22Z

Update to doc-diff. * jk/doc-diff-parallel: doc-diff: use single-colon rule in rendering Makefile

Documentation: clarify that `-h` alone stands for `help`

2020-02-27T22:14:01Z

We seem to be getting new users who get confused every 20 months or so with this "-h consistently wants to give help, but the commands to which `-h` may feel like a good short-form option want it to mean something else." compromise. Let's make sure that the readers know that `git cmd -h` (with no other arguments) is a way to get usage text, even for commands like ls-remote and grep. Also extend the description that is already in gitcli.txt, as it is clear that users still get confused with the current text. Signed-off-by: Junio C Hamano

check-ignore: fix documentation and implementation to match

2020-02-18T23:28:58Z

check-ignore has two different modes, and neither of these modes has an implementation that matches the documentation. These modes differ in whether they just print paths or whether they also print the final pattern matched by the path. The fix is different for both modes, so I'll discuss both separately. === First (default) mode === The first mode is documented as: For each pathname given via the command-line or from a file via --stdin, check whether the file is excluded by .gitignore (or other input files to the exclude mechanism) and output the path if it is excluded. However, it fails to do this because it did not account for negated patterns. Commands other than check-ignore verify exclusion rules via calling ... -> treat_one_path() -> is_excluded() -> last_matching_pattern() while check-ignore has a call path of the form: ... -> check_ignore() -> last_matching_pattern() The fact that the latter does not include the call to is_excluded() means that it is susceptible to to messing up negated patterns (since that is the only significant thing is_excluded() adds over last_matching_pattern()). Unfortunately, we can't make it just call is_excluded(), because the same codepath is used by the verbose mode which needs to know the matched pattern in question. This brings us to... === Second (verbose) mode === The second mode, known as verbose mode, references the first in the documentation and says: Also output details about the matching pattern (if any) for each given pathname. For precedence rules within and between exclude sources, see gitignore(5). The "Also" means it will print patterns that match the exclude rules as noted for the first mode, and also print which pattern matches. Unless more information is printed than just pathname and pattern (which is not done), this definition is somewhat ill-defined and perhaps even self-contradictory for negated patterns: A path which matches a negated exclude pattern is NOT excluded and thus shouldn't be printed by the former logic, while it certainly does match one of the explicit patterns and thus should be printed by the latter logic. === Resolution == Since the second mode exists to find out which pattern matches given paths, and showing the user a pattern that begins with a '!' is sufficient for them to figure out whether the pattern is excluded, the existing behavior is desirable -- we just need to update the documentation to match the implementation (i.e. it is about printing which pattern is matched by paths, not about showing which paths are excluded). For the first or default mode, users just want to know whether a pattern is excluded. As such, the existing documentation is desirable; change the implementation to match the documented behavior. Finally, also adjust a few tests in t0008 that were caught up by this discrepancy in how negated paths were handled. Signed-off-by: Elijah Newren Signed-off-by: Junio C Hamano

doc-diff: use single-colon rule in rendering Makefile

2020-02-18T21:53:30Z

When rendering the troff manpages to text via "man", we create an ad-hoc Makefile and feed it to "make". The purpose here is two-fold: - reuse results from a prior interrupted render of the same tree - use make's -j option to build in parallel But the second part doesn't seem to work (at least with my version of GNU make, 4.2.1). It just runs one render at a time. We use a double-colon "all" rule for each file, like: all:: foo foo: ...actual render recipe... all:: bar bar: ...actual render recipe... ...and so on... And it's this double-colon that seems to inhibit the parallelism. We can just switch to a regular single-colon rule. Even though we do have multiple rules for "all" here, we don't have any recipe to execute for "all" (we only care about triggering its dependencies), so the distinction is irrelevant. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

doc/config/push: use longer "--" line for preformatted example

2020-02-18T21:48:31Z

The example for the push.pushOption config tries to create a preformatted section, but uses only two dashes in its "--" line. In AsciiDoc this is an "open block", with no type; the lines end up jumbled because they're formatted as paragraphs. We need four or more dashes to make it a "listing block" that will respect the linebreaks. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano