doc: git-add: clarify intro & add an example

- 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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index b7a735824d6ce07c6438f190c5c7c1ab1395c478..19f99b0e7f6f09a3814d8d346b1a40c23f2f60b3 100644 (file)
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -16,18 +16,18 @@ git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-
 
 DESCRIPTION
 -----------
-This command updates the index using the current content found in
-the working tree, to prepare the content staged for the next commit.
-It typically adds the current content of existing paths as a whole,
-but with some options it can also be used to add content with
-only part of the changes made to the working tree files applied, or
-remove paths that do not exist in the working tree anymore.
-
-The "index" holds a snapshot of the content of the working tree, and it
-is this snapshot that is taken as the contents of the next commit.  Thus
-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 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.
+
+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`.
 
 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