git/Documentation/git-commit.txt, branch v2.30.2

doc: preparatory clean-up of description on the sign-off option

2020-10-20T18:57:35Z

Almost identical text on the signed-off-by trailer appears in the documentation for "git commit" and "git merge" and its friends. Introduce a new signoff-option.txt file to be shared. A couple of things of note are: - The short-form "-s" is available only in "git commit", but not in commands that are friends of "git merge", as it is used as a short-hand for "--strategy". - The original lacks description on the negated "--no-signoff" form on "git commit" side, but it equally is applicable. It however was unclear in the original text that not adding a Signed-off-by trailer is the default, so rephrase to explain it as a way to countermand a --signoff option that appeared earlier on the same command line. This is in preparation to apply a further clarification on what exactly the Signed-off-by trailer means. Suggested-by: Philippe Blain Signed-off-by: Junio C Hamano Reviewed-by: Taylor Blau Reviewed-by: Bradley M. Kuhn Signed-off-by: Junio C Hamano

Documentation: reword commit --no-gpg-sign

2020-04-03T18:37:22Z

Merge with --gpg-sign option, and clarify that --no-gpg-sign also override earlier --gpg-sign. Signed-off-by: Đoàn Trần Công Danh Signed-off-by: Junio C Hamano

doc: provide guidance on user.name format

2020-01-22T20:27:08Z

It's a frequent misconception that the user.name variable controls authentication in some way, and as a result, beginning users frequently attempt to change it when they're having authentication troubles. Document that the convention is that this variable represents some form of a human's personal name, although that is not required. In addition, address concerns about whether Unicode is supported. Use the term "personal name" as this is likely to draw the intended contrast, be applicable across cultures which may have different naming conventions, and be easily understandable to people who do not speak English as their first language. Indicate that "some form" is conventionally used, as people may use a nickname or preferred name instead of a full legal name. Point users who may be confused about authentication to an appropriate configuration option instead. Provide a shortened form of this information in the configuration option description. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano

docs: expand on possible and recommended user config options

2020-01-22T20:27:08Z

In the section on setting author and committer information, we omit the author.* and committer.* variables, so mention them for completeness. In addition, guide users to the typical case: simply setting user.name and user.email, which are recommended if one does not need complex configuration. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano

doc: move author and committer information to git-commit(1)

2020-01-22T20:27:08Z

While at one time it made perfect sense to store information about configuring author and committer information in the documentation for git commit-tree, in modern Git that operation is seldom used. Most users will use git commit and expect to find comprehensive documentation about its use in the manual page for that command. Considering that there is significant confusion about how one is to use the user.name and user.email variables, let's put as much documentation as possible into an obvious place where users will be more likely to find it. In addition, expand the environment variables section to describe their use more fully. Even though we now describe all of the options there and in the configuration settings documentation, preserve the existing text in git-commit.txt so that people can easily reason about the ordering of the various options they can use. Explain the use of the author.* and committer.* options as well. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano

commit: support the --pathspec-from-file option

2019-11-20T04:01:53Z

Decisions taken for simplicity: 1) For now, `--pathspec-from-file` is declared incompatible with `--interactive/--patch`, even when is not `stdin`. Such use case it not really expected. Also, it would require changes to `interactive_add()`. 2) It is not allowed to pass pathspec in both args and file. Signed-off-by: Alexandr Miloslavskiy Signed-off-by: Junio C Hamano

doc: commit: synchronize description

2019-11-20T04:01:53Z

`git add` shows an example of good writing, follow it. This also better disambiguates ... header. Signed-off-by: Alexandr Miloslavskiy Signed-off-by: Junio C Hamano

Documentation: wrap blocks with "--"

2019-09-09T18:05:51Z

The documentation for each of these options contains a list. After the list, AsciiDoc interprets the continuation as a continuation of the *list*, not as a continution of the larger block. As a result, we get too much indentation. Wrap the entire blocks in "--" to fix this. With Asciidoctor, this commit is a no-op, and the two programs now render these identically. These two files share the same problem and indeed, they both document `--untracked-files` in quite similar ways. I haven't checked to what extent that is intentional or warranted, and to what extent they have simply drifted apart. I consider such an investigation and possible cleanup as out of scope for this commit and this patch series. Signed-off-by: Martin Ågren Signed-off-by: Junio C Hamano

doc: promote "git restore"

2019-05-07T04:04:48Z

The new command "git restore" (together with "git switch") are added to avoid the confusion of one-command-do-all "git checkout" for new users. They are also helpful to avoid ambiguous context. For these reasons, promote it everywhere possible. This includes documentation, suggestions/advice from other commands. One nice thing about git-restore is the ability to restore "everything", so it can be used in "git status" advice instead of both "git checkout" and "git reset". The three commands suggested by "git status" are add, rm and restore. "git checkout" is also removed from "git help" (i.e. it's no longer considered a commonly used command) Signed-off-by: Nguyễn Thái Ngọc Duy Signed-off-by: Junio C Hamano

git-commit.txt: better description what it does

2019-02-04T18:00:01Z

The description of git-commit jumps right into the commit content, which is important, but it fails to mention how the commit is "added" to the repository. Update the first paragraph saying a bit more about branch update to fill this gap. While at there, add a couple linkgit references when the command is first mentioned. Helped-by: Eric Sunshine Signed-off-by: Nguyễn Thái Ngọc Duy Signed-off-by: Junio C Hamano