This is v5 of a series improving the documentation to cover common user
misconceptions.
Changes from v4:
* Add a reference to git(1) for environment variables.
* Remove duplicated text.
* Add Peff's sign-off.
Changes from v3:
* Restructure docs around git-commit(1).
* Improve wording about templating as suggested by Peff.
* Document ordering between user.*, author.*, and committer.*.
* Document the environment variables more thoroughly.
Changes from v2:
* Move author and committer information to git-commit(1) where people
will look for it.
* Move guidance on user.name format to git-commit(1) as well and mention
a shortened form of the advice in the `user.name` description.
* Use a parenthetical to describe a "personal name" without contrasting
it with a username.
* Offer a potential solution for people who want to ignore tracked
files by recommending a templating mechanism.
* Be slightly more verbose about why memory is wasted with
http.postBuffer.
Changes from v1:
* Remove parenthetical which was confusing.
* Add two more patches.
brian m. carlson (5):
doc: move author and committer information to git-commit(1)
docs: expand on possible and recommended user config options
doc: provide guidance on user.name format
doc: dissuade users from trying to ignore tracked files
docs: mention when increasing http.postBuffer is valuable
Documentation/config/http.txt | 8 ++++++
Documentation/config/user.txt | 7 +++++-
Documentation/git-commit-tree.txt | 22 +---------------
Documentation/git-commit.txt | 40 +++++++++++++++++++++++++++---
Documentation/git-update-index.txt | 16 ++++++++++++
Documentation/git.txt | 27 ++++++++++++++++++--
6 files changed, 93 insertions(+), 27 deletions(-)
Range-diff against v4:
1: 0433792871 ! 1: fe2dcea128 doc: move author and committer information to git-commit(1)
@@ Documentation/config/user.txt: committer.email::
Instruct Git to avoid trying to guess defaults for `user.email`
## Documentation/git-commit-tree.txt ##
-@@ Documentation/git-commit-tree.txt: tend to just write the result to the file that is pointed at by
- `.git/HEAD`, so that we can always see what the last committed
- state was.
-
-+A commit comment is read from stdin. If a changelog
-+entry is not provided via "<" redirection, 'git commit-tree' will just wait
-+for one to be entered and terminated with ^D.
-+
- OPTIONS
- -------
- <tree>::
@@ Documentation/git-commit-tree.txt: OPTIONS
Do not GPG-sign commit, to countermand a `--gpg-sign` option
given earlier on the command line.
2: 8745faf560 = 2: 8d4940efab docs: expand on possible and recommended user config options
3: 277a151e2c ! 3: a82522e479 doc: provide guidance on user.name format
@@ Documentation/config/user.txt: committer.email::
- See linkgit:git-commit[1] for more information.
++
+Note that the `name` forms of these variables conventionally refer to
-+some form of a personal name.
-+See linkgit:git-commit[1] for more information on these settings and
-+the `credential.username` option if you're looking for authentication
-+credentials instead.
++some form of a personal name. See linkgit:git-commit[1] and the
++environment variables section of linkgit:git[1] for more information on
++these settings and the `credential.username` option if you're looking
++for authentication credentials instead.
user.useConfigOnly::
Instruct Git to avoid trying to guess defaults for `user.email`
4: 6b593861b5 ! 4: 1c95dec93e doc: dissuade users from trying to ignore tracked files
@@ Commit message
common case of configuration files, since there are well-known
approaches used successfully in many environments.
+ Signed-off-by: Jeff King <peff@xxxxxxxx>
Signed-off-by: brian m. carlson <sandals@xxxxxxxxxxxxxxxxxxxx>
## Documentation/git-update-index.txt ##
5: 960c80eda3 = 5: 51335b1a49 docs: mention when increasing http.postBuffer is valuable
