Subject: [PATCH v2 0/4] doc: git-add: clarify DESCRIPTION section

From: "Julia Evans via GitGitGadget" <[email-masked]>
Date: Wed, 13 Aug 2025 23:20:14 +0000

* Remove changes to SYNOPSIS
 * Add a sentence describing what "the index" is.
 * Shorten the terminology note
 * Say "The git add command" instead of git add

Julia Evans (4):
  doc: git-add: start man page with an example
  doc: git-add: simplify discussion of ignored files
  doc: git-add: make explanation less dry
  doc: git-add: explain inconsistent terminology

 Documentation/git-add.adoc | 64 ++++++++++++++++++++------------------
 1 file changed, 33 insertions(+), 31 deletions(-)

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

Range-diff vs v1:

 1:  3a2cc38b72f < -:  ----------- doc: git-add: remove options from SYNOPSIS
 2:  310d2c1d8f7 ! 1:  d041d09589b doc: git-add: start man page with an example
     @@ Documentation/git-add.adoc: git-add(1)
       
       SYNOPSIS
       --------
     -@@ Documentation/git-add.adoc: git add [<options>] [--] [<pathspec>...]
     +@@ Documentation/git-add.adoc: git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-
       
       DESCRIPTION
       -----------
     @@ Documentation/git-add.adoc: git add [<options>] [--] [<pathspec>...]
      -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 (also known as "staging area") to
     -+prepare for a commit.
     ++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.
      +
      +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
 3:  3f4ab615069 = 2:  63c9e0361dc doc: git-add: simplify discussion of ignored files
 4:  34b09deb61a ! 3:  ce1eafb0286 doc: git-add: make explanation less dry
     @@ Documentation/git-add.adoc: You can also add only part of your changes to a file
      -adds the content of the specified file(s) at the time the add command is
      -run; if you want subsequent changes included in the next commit, then
      -you must run `git add` again to add the new content to the index.
     -+`git add` only adds the changes at the time that you run it. If you edit
     -+`file.c` after adding it, you need to run `git add file.c` again before
     -+committing.
     ++The `git add` command only adds the changes at the time that you run it.
     ++If you edit `file.c` after adding it, you need to run `git add file.c`
     ++again before committing.
       
      -The `git status` command can be used to obtain a summary of which
      -files have changes that are staged for the next commit.
 5:  f7e8e4c63a1 ! 4:  9e595f9ad59 doc: git-add: explain inconsistent terminology
     @@ Documentation/git-add.adoc: exact filename of an ignored file (e.g. `git add ign
       add` will fail with a list of ignored files. Otherwise it will silently
       ignore the file.
       
     -+TERMINOLOGY NOTE
     -+----------------
     -+
     ++[NOTE]
      +Git uses the terms "staging area", "index" and "cache" interchangeably
     -+for historical reasons. Many commands have flags like `--staged`,
     -+`--index`, or `--cached`, and they all refer to the index.
     ++for historical reasons.
      +
       OPTIONS
       -------

-- 
gitgitgadget