Skip to content

Documentation for common user misconceptions

brian m. carlson git 6 versions – In review

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v5 Latest5 patches 2 repliesIn review
  2. v4 posting 2/25 patches 6 repliesSuperseded
  3. v4 posting 1/20 of 6 patches 1 replySuperseded
Earlier versions · 3
VersionPostedPatchesRepliesStatus
v34 patches20 repliesSuperseded
v23 patches6 repliesSuperseded
v11 patch2 repliesSuperseded

Changes in v5 from the cover letter

* Add a reference to git(1) for environment variables.
* Remove duplicated text.
* Add Peff's sign-off.

Patches in v5 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/5doc: move author and committer information to git-commit(1)Documentation/config/user.txt Documentation/git-commit-tree.txt Documentation/git-commit.txt +1 more+51 -270 replies
2/5docs: expand on possible and recommended user config optionsDocumentation/git-commit.txt+7 -00 replies
3/5doc: provide guidance on user.name formatDocumentation/config/user.txt Documentation/git-commit.txt+12 -10 replies
4/5doc: dissuade users from trying to ignore tracked filesDocumentation/git-update-index.txt+16 -00 replies
5/5docs: mention when increasing http.postBuffer is valuableDocumentation/config/http.txt+8 -00 replies

Reviews trailers per patch

None of the 5 patches has a Reviewed-by or Acked-by of their own; the series has one for all of them.

PatchEmily Shaffer
SeriesR-b
1/5
2/5
3/5
4/5
5/5

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.

Read the v5 thread

Cover letter [PATCH v5 0/5] Documentation for common user misconceptions

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 <[email protected]>

## Documentation/git-update-index.txt ##
5: 960c80eda3 = 5: 51335b1a49 docs: mention when increasing http.postBuffer is valuable