git/help.h, branch v2.45.3

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: add --no-[external-commands|aliases] for use with --all

2022-02-23T21:41:37Z

Add the ability to only emit git's own usage information under --all. This also allows us to extend the "test_section_spacing" tests added in a preceding commit to test "git help --all" output. Previously we could not do that, as the tests might find a git-* command in the "$PATH", which would make the output differ from one setup to another. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

help: move column config discovery to help.c library

2021-09-23T17:30:43Z

When a git_config() call was added in dbfae689690 (help: reuse print_columns() for help -a, 2012-04-13) to read the column config we'd always use the resulting "colopts" variable. Then in 63eae83f8f3 (help: add "-a --verbose" to list all commands with synopsis, 2018-05-20) we started only using the "colopts" config under "--all" if "--no-verbose" was also given, but the "git_config()" call was not moved inside the "verbose" branch of the code. This change effectively does that, we'll only call list_commands() under "--all --no-verbose", so let's have it look up the config it needs. See 26c7d067832 (help -a: improve and make --verbose default, 2018-09-29) for another case in help.c where we look up config. The get_colopts() function is named for consistency with the existing get_alias() function added in 26c7d067832. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

help: do not expect built-in commands to be hardlinked

2020-10-07T22:25:10Z

When building with SKIP_DASHED_BUILT_INS=YesPlease, the built-in commands are no longer present in the `PATH` as hardlinks to `git`. As a consequence, `load_command_list()` needs to be taught to find the names of the built-in commands from elsewhere. This only affected the output of `git --list-cmds=main`, but not the output of `git help -a` because the latter includes the built-in commands by virtue of them being listed in command-list.txt. The bug was detected via a patch series that turns the merge strategies included in Git into built-in commands: `git merge -s help` relies on `load_command_list()` to determine the list of available merge strategies. Signed-off-by: Johannes Schindelin Signed-off-by: Junio C Hamano

help: drop usage of 'common' and 'useful' for guides

2020-08-05T01:34:01Z

Since 1b81d8cb19 (help: use command-list.txt for the source of guides, 2018-05-20), all man5/man7 guides listed in command-list.txt appear in the output of 'git help -g'. However, 'git help -g' still prefixes this list with "The common Git guides are:", which makes one wonder if there are others! In the same spirit, the man page for 'git help' describes the '--guides' option as listing 'useful' guides, which is not false per se but can also be taken to mean that there are other guides that exist but are not useful. Instead of 'common' and 'useful', use 'Git concept guides' in both places. To keep the code in line with this change, rename help.c::list_common_guides_help to list_guides_help. Signed-off-by: Philippe Blain Signed-off-by: Junio C Hamano

bugreport: gather git version and build info

2020-04-16T22:23:42Z

Knowing which version of Git a user has and how it was built allows us to more precisely pin down the circumstances when a certain issue occurs, so teach bugreport how to tell us the same output as 'git version --build-options'. It's not ideal to directly call 'git version --build-options' because that output goes to stdout. Instead, wrap the version string in a helper within help.[ch] library, and call that helper from within the bugreport library. Signed-off-by: Emily Shaffer Signed-off-by: Junio C Hamano

help: move list_config_help to builtin/help

2020-04-16T22:22:16Z

Starting in 3ac68a93fd2, help.o began to depend on builtin/branch.o, builtin/clean.o, and builtin/config.o. This meant that help.o was unusable outside of the context of the main Git executable. To make help.o usable by other commands again, move list_config_help() into builtin/help.c (where it makes sense to assume other builtin libraries are present). When command-list.h is included but a member is not used, we start to hear a compiler warning. Since the config list is generated in a fairly different way than the command list, and since commands and config options are semantically different, move the config list into its own header and move the generator into its own script and build rule. For reasons explained in 976aaedc (msvc: add a Makefile target to pre-generate the Visual Studio solution, 2019-07-29), some build artifacts we consider non-source files cannot be generated in the Visual Studio environment, and we already have some Makefile tweaks to help Visual Studio to use generated command-list.h header file. Do the same to a new generated file, config-list.h, introduced by this change. Helped-by: Junio C Hamano Signed-off-by: Emily Shaffer

help: make help_unknown_ref() NORETURN

2019-08-30T17:22:42Z

Announce that calling help_unknown_ref() exits the program. Signed-off-by: René Scharfe Signed-off-by: Junio C Hamano

*.[ch]: manually align parameter lists

2019-05-05T06:20:10Z

In previous patches, extern was mechanically removed from function declarations without care to formatting, causing parameter lists to be misaligned. Manually format changed sections such that the parameter lists should be realigned. Viewing this patch with 'git diff -w' should produce no output. Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano