Re: [PATCH v2 1/4] doc: git-add: start man page with an example

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> -git-add - Add file contents to the index
> +git-add - Add new or changed files to the index

Does it add much value to say "new or changed" here?  The command can
also be used to "stage" a removal of a path, e.g.

    $ rm tracked-file
    $ git add -u

so if the updated text is an attempt to give more details on what
kind of modifications are captured, it would be better to say "add
new, removed, or modified files".

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

I won't repeat myself about change-snapshot duality, but I do not
think the new text is the best we can do.

    Update contents recorded in the index to prepare for the next
    commit.  The index (also known as "staging area") is where Git
    stores the contents 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
> +changes, you can run:

Likewise.  "and want to record the resulting contents".

> ...
> -Please see linkgit:git-commit[1] for alternative ways to add content to a
> -commit.

In the original, this comment does look a bit out of place (as the
text around there does not talk about `git commit`), but as you said
that by default 'git commit' makes an as-is commit above, it may be
a good idea to move this sentence there.  `git commit <pathspec>` is
a handy thing to know even for beginners, and making your next commit
is what the user is working towards by using "git add".