* 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 terminologyJulia Evans via GitGitGadget <gitgitgadget@gmail.com>