Re: [1.8.0] use 'stage' term consistently

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: May 20, 2012, 11:49 UTC
Message-ID: <CAMP44s2cGeQq3V=jS1Xjg-S0-rMyKS79XFN9yFm+4KxMo963OA@mail.gmail.com>
In-Reply-To: <20120519060031.GB23799@burratino>

On Sat, May 19, 2012 at 8:00 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

> For the sake of having a proposal: :)
>
>  - the file representing the content of the next command would still
>   be called .git/index and not be renamed

Agreed, that is an implementation detail anyway; the changes should be done with how the a typical user interacts with git, and a typical user doesn't need to know the index exists.

Show 19 quoted lines

>  - adding and removing content to and from the index is "staging a
>   change".  Since it is not safe to assume the reader already
>   knows what that means, when working on the manual authors should
>   try to imagine themselves as a new user and make the text
>   unambiguous enough to help such a person.
>
>   For example, the first sentence of the "git add" manual:
>
>        This command updates the index using the current content found in the
>        working tree, to prepare the content staged for the next commit.
>
>   should not be changed to:
>
>        This command updates the staging area using ...
>
>   because that just makes it less clear.  Before, it said "the index"
>   and I could look in the glossary or the .git directory to at least
>   find what file it was talking about.  Afterwards, it is using an
>   everyday term and the new user wonders "which staging area?".

The git's staging area, of course. How is that not clear?

If the (new) user wants to know more about the staging area, she can read about it, just like she currently can. A 'man git staging-area' might actually help.

However, there's no 'man git index', or anything like that, so where do you suppose new users currently look for information when they wonder "what index"? And looking into the .git directory for an "index" file? Seriously? I doubt any new user would do that, I haven't even done so myself. The whole point of documentation is to be user *friendly*.

>   Instead, it would be better to change it to something like:
>
>        This command modifies the content staged for the next commit
>        using content found in the working tree.  It typically adds ...

Show 6 quoted lines

>        The "index" file (see gitindex(5)) typically holds a snapshot of
>        the content of the working tree, and it is this snapshot that is
>        taken as the content of the next commit.  Thus after making any
>        changes to the working directory, and before running the commit
>        command, you must use the add command to add any new or modified
>        files.

I find this paragraph completely unnecessary. This is useless distraction; the user wants to know about 'git add', she doesn't need to know about the index, and we should hide it from her.

Instead, the 'git add' documentation should point to the 'man git staging-area', and there, hidden somewhere is the implementation details; the index, and all the gory details.

Cheers.

-- 
Felipe Contreras