git/Documentation/gitcli.txt, branch v2.48.2

gitcli.txt: typeset pathnames as monospace

2025-01-03T16:23:59Z

Commit 1bc1e94091 (doc: option value may be separate for valid reasons, 2024-11-25) added a paragraph discussing tilde-expansion of, e.g., ~/directory/file. The tilde character has a special meaning to asciidoc tools. In this particular case, AsciiDoc matches up the two tildes in "e.g. ~/directory/file or ~u/d/f" and sets the text between them using subscript. In the manpage, where subscripting is not possible, this renders as "e.g. /directory/file oru/d/f". These paths are literal values, which our coding guidelines want typeset as verbatim using backticks. Do that. One effect of this is indeed that the asciidoc tools stop interpreting tilde and other special characters. Signed-off-by: Martin Ågren Signed-off-by: Junio C Hamano

doc: option value may be separate for valid reasons

2024-11-25T05:20:15Z

Even though `git help cli` recommends users to prefer using "--option=value" over "--option value", there can be reasons why giving them separately is a good idea. One reason is that shells do not perform tilde expansion for `--option=~/path/name` but they expand `--options ~/path/name` just fine. This is not a problem for many options whose option parsing is properly written using OPT_FILENAME(), because the value given to OPT_FILENAME() is tilde-expanded internally by us, but some commands take a pathname as a mere string, which needs this trick to have the shell help us. I think the reason we originally decided to recommend the stuck form was because an option that takes an optional value requires you to use it in the stuck form, and it is one less thing for users to worry about if they get into the habit to always use the stuck form. But we should be discouraging ourselves from adding an option with an optional value in the first place, and we might want to weaken the current recommendation. In any case, let's describe this one case where it is necessary to use the separate form, with an example. Reviewed-by: Eric Sunshine Signed-off-by: Junio C Hamano

gitcli: drop mention of “non-dashed form”

2024-03-01T18:45:01Z

Git builtins used to be called like e.g. `git-commit`, not `git commit` (*dashed form* and *non-dashed form*, respectively). The dashed form was deprecated in version 1.5.4 (2006). Now only a few commands have an alternative dashed form when `SKIP_DASHED_BUILT_INS` is active.[1] The mention here is from 2f7ee089dff (parse-options: Add a gitcli(5) man page., 2007-12-13), back when the deprecation was relatively recent. These days though it seems like an irrelevant point to make to budding CLI scripters—you don’t have to warn against a style that probably doesn’t even work on their git(1) installation. † 1: 179227d6e21 (Optionally skip linking/copying the built-ins, 2020-09-21) Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

documentation: add missing article

2023-10-09T19:06:29Z

Diff best viewed with --color-diff. Signed-off-by: Elijah Newren Signed-off-by: Junio C Hamano

documentation: fix singular vs. plural

2023-10-09T19:06:29Z

Diff best viewed with --color-diff. Signed-off-by: Elijah Newren Signed-off-by: Junio C Hamano

documentation: fix verb tense

2023-10-09T19:06:29Z

Diff best viewed with --color-diff. Signed-off-by: Elijah Newren Signed-off-by: Junio C Hamano

git-cli.txt: clarify "options first and then args"

2022-01-17T19:42:25Z

There are some commands permit the user whether to provide options first before args, or the reverse order. For example: git push --dry-run And: git push --dry-run Both of them is supported, but some commands do not, for instance: git ls-remote --heads And: git ls-remote --heads If only has one ref and it's name is "refs/heads/--heads", you will get the same result, otherwise will not.This is because the former in the second example will parse "--heads" as an "option" which means to limit to only "refs/heads" when listing the remote references, the latter treat "--heads" as an argument which means to filter the result list with the given pattern. Therefore, we want to specify a bit more in "gitcli.txt" about the way we recommend and help to resolve the ambiguity around some git command usage. The related disscussions locate at [1]. By the way, there are some issues with lowercase letters in the document, which have been modified together. [1] https://public-inbox.org/git/cover.1642129840.git.dyroneteng@gmail.com/ Signed-off-by: Teng Long Signed-off-by: Junio C Hamano

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

2020-03-11T17:58:16Z

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`

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

Merge branch 'dl/lore-is-the-archive'

2019-12-06T23:09:24Z

Publicize lore.kernel.org mailing list archive and use URLs pointing into it to refer to notable messages in the documentation. * dl/lore-is-the-archive: doc: replace LKML link with lore.kernel.org RelNotes: replace Gmane with real Message-IDs doc: replace MARC links with lore.kernel.org