[v5,0/5] Documentation for common user misconceptions
mbox series

Message ID 20200122034543.18927-1-sandals@crustytoothpaste.net
Headers show
Series
  • Documentation for common user misconceptions
Related show

Message

brian m. carlson Jan. 22, 2020, 3:45 a.m. UTC
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@peff.net>
         Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
     
      ## Documentation/git-update-index.txt ##
5:  960c80eda3 = 5:  51335b1a49 docs: mention when increasing http.postBuffer is valuable

Comments

Jeff King Jan. 22, 2020, 3:52 a.m. UTC | #1
On Wed, Jan 22, 2020 at 03:45:38AM +0000, brian m. carlson wrote:

> 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.

Thanks, just looking at the interdiff I think this addresses all of my
comments.

-Peff
Emily Shaffer Jan. 22, 2020, 7:25 p.m. UTC | #2
On Wed, Jan 22, 2020 at 03:45:38AM +0000, brian m. carlson wrote:
> This is v5 of a series improving the documentation to cover common user
> misconceptions.

Thanks - it makes me happy to see these kinds of clarifications come
through.

Reviewed-by: Emily Shaffer <emilyshaffer@google.com>