[PATCH v3 0/3] doc: git-add: clarify DESCRIPTION section

["Julia Evans via GitGitGadget" <gitgitgadget@gmail.com>]

 * Emphasize "contents" more than "files" in the introduction
 * Delete the terminology note, and just keep a single parenthetical "(also
   known as "staging area")"
 * Be more explicit about what "By default" means
 * Don't mention git diff --cached, mentioning more and more related
   commands felt like it was starting to get messy (what about git diff?
   what about git reset? what about git rm?).
 * Leave the "This command can be performed multiple times before a
   commit"... paragraph alone since the only 2 users who commented on it
   said it was clear and helpful already.
 * Move "Please see linkgit:git-commit[1].." back to the end, where it used
   to be

Julia Evans (2):
  doc: git-add: clarify intro & add an example
  doc: git-add: simplify discussion of ignored files

Junio C Hamano (1):
  Git 2.51

 Documentation/git-add.adoc | 34 ++++++++++++++++------------------
 GIT-VERSION-GEN            |  2 +-
 2 files changed, 17 insertions(+), 19 deletions(-)


base-commit: e5ab6b3e5a3f0a94a429526e0fe6f491955ac053
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1952%2Fjvns%2Fclarify-add-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1952/jvns/clarify-add-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1952

Range-diff vs v2:

 -:  ----------- > 1:  c44beea485f Git 2.51
 1:  d041d09589b ! 2:  080720c0599 doc: git-add: start man page with an example
     @@ Metadata
      Author: Julia Evans <julia@jvns.ca>
      
       ## Commit message ##
     -    doc: git-add: start man page with an example
     +    doc: git-add: clarify intro & add an example
      
     -    - Replace the intro paragraph of the `git-add` man page with an
     -      example to try to clarify it for new users. The goal here is use less
     -      jargon but communicate essentially the same information.
     -    - Give an example of how to add only part of the changes to the file
     -    - Remove the snapshot-based explanation of the index and replace it with
     -      a diff-based explanation because I don't feel that it's useful in this
     -      context to emphasize  that git uses a snapshot-based model: the main
     -      way most git users interact with the index is through `git diff` or
     -      `git status`, which is a completely diff-based view of the index.
     +    - Add a basic example of how "git add" is normally used
     +    - It's not technically true that you *must* use the `add` command to
     +      add changes before running `git commit`, because `git commit -a`
     +      exists. Instead say that you *can* use the `add` command.
     +    - Mention early on that "index" is another word for "staging area",
     +      since Git very rarely uses the word "index" in its output
     +      (`git status`) uses the term "staged", and many Git users are
     +      unfamiliar with the term "index"
     +    - Remove "It typically adds" (it's not clear what "typically" means),
     +      and instead mention that `git add -p` can be used to add
     +      partial contents
     +    - Currently the introduction is somewhat repetitive ("to prepare the
     +      content staged for the next commit" ... "this snapshot that is taken
     +      as the contents of the next commit."), replace with a single sentence
     +      ("The "index" [...] is where Git stores the contents of the next
     +      commit.")
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## Documentation/git-add.adoc ##
     -@@ Documentation/git-add.adoc: git-add(1)
     - 
     - NAME
     - ----
     --git-add - Add file contents to the index
     -+git-add - Add new or changed files to the index
     - 
     - SYNOPSIS
     - --------
      @@ Documentation/git-add.adoc: git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-
       
       DESCRIPTION
     @@ Documentation/git-add.adoc: git add [--verbose | -v] [--dry-run | -n] [--force |
      -after making any changes to the working tree, and before running
      -the commit command, you must use the `add` command to add any new or
      -modified files to the index.
     -+Add new or changed files to the index to prepare for a commit. The
     -+"index" (also known as "staging area") is where Git stores the changes
     -+that will be in the next commit.
     ++Add contents of new or changed files to the index. The "index" (also
     ++known as "staging area") is where Git stores the contents of the next
     ++commit.
      +
     -+By default, `git commit` only commits changes that you've added to the
     -+index. For example, if you've edited `file.c` and want to commit your
     -+changes, you can run:
     ++When you run `git commit` without any other arguments, it will only
     ++commit staged changes. For example, if you've edited `file.c` and want
     ++to commit your changes to that file, you can run:
      +
      +   git add file.c
      +   git commit
      +
      +You can also add only part of your changes to a file with `git add -p`.
     -+Please see linkgit:git-commit[1] for alternative ways to add content to
     -+a commit.
       
       This command can be performed multiple times before a commit.  It only
       adds the content of the specified file(s) at the time the add command is
     -@@ Documentation/git-add.adoc: directory recursion or filename globbing performed by Git (quote your
     - globs before the shell) will be silently ignored.  The `git add` command can
     - be used to add ignored files with the `-f` (force) option.
     - 
     --Please see linkgit:git-commit[1] for alternative ways to add content to a
     --commit.
     --
     --
     - OPTIONS
     - -------
     - `<pathspec>...`::
 2:  63c9e0361dc ! 3:  fc2ec305a9e doc: git-add: simplify discussion of ignored files
     @@ Commit message
      
          - Mention the --force option earlier
          - Remove the explanation of shell globbing vs git's internal glob
     -      system, it's a common gotcha but I don't think this is an appropriate
     -      place to explain that concept. There's some discussion of the gotchas
     -      around globbing and `git add` in the EXAMPLES section which I think
     -      is clearer.
     +      system, since users are confused by it and there's a clearer
     +      discussion in the EXAMPLES section.
      
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
     @@ Documentation/git-add.adoc: you must run `git add` again to add the new content
      -directory recursion or filename globbing performed by Git (quote your
      -globs before the shell) will be silently ignored.  The `git add` command can
      -be used to add ignored files with the `-f` (force) option.
     -+`git add` will not add ignored files by default. You can use the
     -+`--force` option to add ignored files. If you explicitly specify the
     -+exact filename of an ignored file (e.g. `git add ignored.txt`), `git
     -+add` will fail with a list of ignored files. Otherwise it will silently
     -+ignore the file.
     ++The `git add` command will not add ignored files by default. You can
     ++use the `--force` option to add ignored files. If you specify the exact
     ++filename of an ignored file, `git add` will fail with a list of ignored
     ++files. Otherwise it will silently ignore the file.
       
     - OPTIONS
     - -------
     + Please see linkgit:git-commit[1] for alternative ways to add content to a
     + commit.
 3:  ce1eafb0286 < -:  ----------- doc: git-add: make explanation less dry
 4:  9e595f9ad59 < -:  ----------- doc: git-add: explain inconsistent terminology

-- 
gitgitgadget