Re: "git help stage" doesn't display git-stage man page

Teemu Likonen [off-list ref] writes:

Junio C Hamano (2008-12-02 22:23 -0800) wrote:

quoted

* The 'master' branch has these since the last announcement
  in addition to the above.

quoted

Scott Chacon (1):
  Add a built-in alias for 'stage' to the 'add' command

I think there's a minor user-interface defect:

    $ git help stage
    No manual entry for gitstage

The patch also breaks the promise made at 1.6.0 that prepending exec path
to $PATH allows you to use the dashed form.

	$ PATH=$(git --exec-path):$PATH
        $ git-stage -p
	xash: git-stage: cmd not found

"git stage" is only a built-in alias but at some point it may become the
primary staging command for new Git users and hence a kind of real Git
command. I think "git help stage" should show the git-stage manual page
(even though it only points to git-add(1)).

I do not think it would ever be _the_ primary command to add the contents
to the index; we are adding it as a training wheel.

When we had the "staging area" discussion, somehow people ended up with
this notion that you somehow *need to* use the same verb and noun.
I.e. "the index is now explained as the _staging area_.  Why isn't the
command to add contents to the staging area called git-stage?" was the
primary argument that lead to this thinking.

I do not think it adds much value to the system to be dogmatic and insist
that you _have to_ use the same verb and noun.  "You add your changes to
the staging area" is a perfectly natural way to explain what you are doing
and where the "add" in git-add command comes from.  It however is Ok to
allow people to use different spelling (i.e. the verb "stage").

In that sense, I think the intention of the patch to add "stage" as an
additional verb, while clearly marking it as a synonym to the primary
command "add", is aimed at the right place and strikes the right balance.

By the way, I think this should fix it, although it is very late and I
have no time to test it tonight myself.

---

 Makefile |    1 +
 1 files changed, 1 insertions(+), 0 deletions(-)

diff --git i/Makefile w/Makefile
index 9577d6f..5158197 100644
--- i/Makefile
+++ w/Makefile

@@ -320,6 +320,7 @@ BUILT_INS += git-merge-subtree$X
 BUILT_INS += git-peek-remote$X
 BUILT_INS += git-repo-config$X
 BUILT_INS += git-show$X
+BUILT_INS += git-stage$X
 BUILT_INS += git-status$X
 BUILT_INS += git-whatchanged$X