From: "Junio C Hamano" <>
Matthieu Moy <> writes:

Junio C Hamano <> writes:

"Philip Oakley" <> writes:

Having said that, it would therefore be better to point folk at gitcli in a few more places, not just the 'see also' line at the very end of
the general 'git' page, and buried within rev-parse.

Didn't we update the very early part of git(1) for exactly for that
reason recently?

Oops I'd forgotten that specific change.

I don't think many people read git(1) directly, as there are many other starting points to learn Git (official tutorial, user-manual, and tens
of very good tutorial on the web).

Many of which is outside what patches made against to my tree would
be able to fix.  I wonder if we can have some mechanism to easily
notify and help the owners of these material to keep them up to

On the other hand, reading git-<command> is probably much more
common, as it is the only place to find exhaustive documentation
about a particular command.

That "people diving into 'git --help <subcmd>', assuming everything
can be learned there" is a problem within the scope of what we could
control.  For obvious reasons, including "glossary-contents" and
"gitcli" at the beginning of documentation for each and every
subcommand is not a useful solution, and referring the prerequisite
reading for them in git(1) was done as the first step to solve that
issue, and you are essentially saying that it is not enough.

So what is the right second step?

a simple link to the gitcli page? or, add the <pathspec> into the checkout options list and a link to a suitable place for that, which can then point to the gitcli.

From my perspective the majority of the top twenty git commands should,
within each of their help pages, have an in-text link into one or other of the various 'guide' style articles, which can then be interconnected to each other. This should give the beginner help by directing them away from the details of a man page for the general issues. That is, distinguish which parts are help for those who aren't sure what they need to know, from the those parts that provide the specfic details for those do know.

I hope to have some documentation patches in the next few days on other small misunderstandings I've seen/made. Just battling my windows / msysgit / pu set-up at the moment.
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to
More majordomo info at

Reply via email to