git/help.c, branch v2.40.2

help.c: fix autocorrect in work tree for bare repository

2022-12-13T01:01:53Z

Currently, auto correction doesn't work reliably for commands which must run in a work tree (e.g. `git status`) in Git work trees which are created from a bare repository. As far as I'm able to determine, this has been broken since commit 659fef199f (help: use early config when autocorrecting aliases, 2017-06-14), where the call to `git_config()` in `help_unknown_cmd()` was replaced with a call to `read_early_config()`. From what I can tell, the actual cause for the unexpected error is that we call `git_default_config()` in the `git_unknown_cmd_config` callback instead of simply returning `0` for config entries which we aren't interested in. Calling `git_default_config()` in this callback to `read_early_config()` seems like a bad idea since those calls will initialize a bunch of state in `environment.c` (among other things `is_bare_repository_cfg`) before we've properly detected that we're running in a work tree. All other callbacks provided to `read_early_config()` appear to only extract their configurations while simply returning `0` for all other config keys. This commit changes the `git_unknown_cmd_config` callback to not call `git_default_config()`. Instead we also simply return `0` for config keys which we're not interested in. Additionally the commit adds a new test case covering `help.autocorrect` in a work tree created from a bare clone. Signed-off-by: Simon Gerber Signed-off-by: Junio C Hamano

Merge branch 'ab/doc-synopsis-and-cmd-usage'

2022-10-28T18:26:54Z

The short-help text shown by "git cmd -h" and the synopsis text shown at the beginning of "git help cmd" have been made more consistent. * ab/doc-synopsis-and-cmd-usage: (34 commits) tests: assert consistent whitespace in -h output tests: start asserting that *.txt SYNOPSIS matches -h output doc txt & -h consistency: make "worktree" consistent worktree: define subcommand -h in terms of command -h reflog doc: list real subcommands up-front doc txt & -h consistency: make "commit" consistent doc txt & -h consistency: make "diff-tree" consistent doc txt & -h consistency: use "[...]" for "zero or more" doc txt & -h consistency: make "annotate" consistent doc txt & -h consistency: make "stash" consistent doc txt & -h consistency: add missing options doc txt & -h consistency: use "git foo" form, not "git-foo" doc txt & -h consistency: make "bundle" consistent doc txt & -h consistency: make "read-tree" consistent doc txt & -h consistency: make "rerere" consistent doc txt & -h consistency: add missing options and labels doc txt & -h consistency: make output order consistent doc txt & -h consistency: add or fix optional "--" syntax doc txt & -h consistency: fix mismatching labels doc SYNOPSIS & -h: use "-" to separate words in labels, not "_" ...

doc txt & -h consistency: add missing options and labels

2022-10-13T16:32:56Z

Fix various issues of SYNOPSIS and -h output syntax where: * Options such as --force were missing entirely * ...or the short option, such as -f * We said "opts" or "options", but could instead enumerate the (small) set of supported options * Options that were missing entirely (ls-remote's --sort=) As we can specify "--sort" multiple times (it's backed by a string-list" it should really be "[(--sort=)...]", which is what "git for-each-ref" lists it as, but let's leave that issue for a subsequent cleanup, and stop at making these consistent. Other "ref-filter.h" users share the same issue, e.g. "git-branch.txt". * For "verify-tag" and "verify-commit" we were missing the "--raw" option. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

help: fix doubled words in explanation for developer interfaces

2022-09-16T16:20:11Z

Signed-off-by: Fangyi Zhou Signed-off-by: Junio C Hamano

git-compat-util.h: use "UNUSED", not "UNUSED(var)"

2022-09-01T17:49:48Z

As reported in [1] the "UNUSED(var)" macro introduced in 2174b8c75de (Merge branch 'jk/unused-annotation' into next, 2022-08-24) breaks coccinelle's parsing of our sources in files where it occurs. Let's instead partially go with the approach suggested in [2] of making this not take an argument. As noted in [1] "coccinelle" will ignore such tokens in argument lists that it doesn't know about, and it's less of a surprise to syntax highlighters. This undoes the "help us notice when a parameter marked as unused is actually use" part of 9b240347543 (git-compat-util: add UNUSED macro, 2022-08-19), a subsequent commit will further tweak the macro to implement a replacement for that functionality. 1. https://lore.kernel.org/git/220825.86ilmg4mil.gmgdl@evledraar.gmail.com/ 2. https://lore.kernel.org/git/220819.868rnk54ju.gmgdl@evledraar.gmail.com/ Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

refs: mark unused each_ref_fn parameters

2022-08-19T19:18:54Z

Functions used with for_each_ref(), etc, need to conform to the each_ref_fn interface. But most of them don't need every parameter; let's annotate the unused ones to quiet -Wunused-parameter. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

git docs: add a category for file formats, protocols and interfaces

2022-08-04T21:12:23Z

Create a new "File formats, protocols and other developer interfaces" section in the main "git help git" manual page and start moving the documentation that now lives in "Documentation/technical/*.git" over to it. This complements the newly added and adjacent "Repository, command and file interfaces" section. This makes the technical documentation more accessible and discoverable. Before this we wouldn't install it by default, and had no ability to build man page versions of them. The links to them from our existing documentation link to the generated HTML version of these docs. So let's start moving those over, starting with just the "bundle-format.txt" documentation added in 7378ec90e1c (doc: describe Git bundle format, 2020-02-07). We'll now have a new gitformat-bundle(5) man page. Subsequent commits will move more git internal format documentation over. Unfortunately the syntax of the current Documentation/technical/*.txt is not the same (when it comes to section headings etc.) as our Documentation/*.txt documentation, so change the relevant bits of syntax as we're moving this over. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

git docs: add a category for user-facing file, repo and command UX

2022-08-04T21:12:23Z

Create a new "Repository, command and file interfaces" section in the main "git help git" manual page. Move things that belong under this new criteria from the generic "Guides" section. The "Guides" section was added in f442f28a81b (git.txt: add list of guides, 2020-08-05). It makes sense to have e.g. "giteveryday(7)" and "gitfaq(7)" listed under "Guides". But placing e.g. "gitignore(5)" in it is stretching the meaning of what a "guide" is, ideally that section should list things similar to "giteveryday(7)" and "gitcore-tutorial(7)". An alternate name that was considered for this new section was "User formats", for consistency with the nomenclature used for man section 5 in general. My man(1) lists it as "File formats and conventions, e.g. /etc/passwd". So calling this "git help --formats" or "git help --user-formats" would make sense for e.g. gitignore(5), but would be stretching it somewhat for githooks(5), and would seem really suspect for the likes of gitcli(7). Let's instead pick a name that's closer to the generic term "User interface", which is really what this documentation discusses: General user-interface documentation that doesn't obviously belong elsewhere. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

help.c: remove common category behavior from drop_prefix() behavior

2022-08-04T21:12:23Z

Change the behavior of the "git" prefix stripping for CAT_guide so that we don't try to strip the "git-" prefix in that case. We should be stripping either "git" or "git-" depending on the category. This change makes it easier to add extra "category" conditions in subsequent commits. Before this we'd in principle strip a "git-" prefix from a "guide" in command-list.txt, in practice we have no such entry there. As we don't have any entry that looks like "git-foo" in command-list.txt this changes nothing in practice, but it makes the intent of the code clearer. In that hypothetical case we'd now strip it down to "-foo", not "foo". When this code was added in cfb22a02ab5 (help: use command-list.h for common command list, 2018-05-10) the only entries in command-list.txt that didn't begin with "git-" were "gitweb" and "gitk". Then when the "guides" special-case was added in 1b81d8cb19d (help: use command-list.txt for the source of guides, 2018-05-20) we had the various "git" (not "git-") prefixed "guide" entries, which the "CAT_guide" case handles. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

help.c: refactor drop_prefix() to use a "switch" statement"

2022-08-04T21:12:23Z

Refactor the drop_prefix() function in in help.c to make it easier to strip prefixes from categories that aren't "CAT_guide". There are no functional changes here, by doing this we make a subsequent functional change's diff smaller. As before we first try to strip "git-" unconditionally, if that works we'll return the stripped string. Then we'll strip "git" if the command is in "CAT_guide". This means that we'd in principle strip "git-foo" down to "foo" if it's in CAT_guide. That doesn't make much sense, and we don't have such an entry in command-list.txt, but let's preserve that behavior for now. While we're at it remove a stray newline that had been added after the "return name;" statement. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano