Jeff King <peff@xxxxxxxx> writes:
> On Tue, Dec 02, 2008 at 11:55:03PM +0100, Johannes Schindelin wrote:
>
>> If the whole thing gets longer than 24 lines, we have to leave some things
>> out. Personally, I consider rm and mv unimportant enough that they could
>> be shown in an extended list, but be left out of the summary page.
>
> For the record, the current output is 26 lines, plus you probably want
> to account for 1 line of the user's next shell prompt. So we are 3 lines
> over already.
>
> Scott's proposal is about grouping the commands more sensibly. Many of
> the complaints are about the length of the output. Maybe we should scrap
> having a list of commands altogether and just point at section-specific
> documentation, each of which could discuss basic commands related to it.
>
> I think there has been mention of task-oriented documentation pointers
> before, and I think this is a place where we would want it.
It might not be a bad idea to make this "top page help" into an
interactive hierarchical help topic browser. You would start a page that
might look like this:
Bootstrapping -- preparing an area to work in
init, clone
Basic -- review, undo and record your changes
diff, status, checkout <path>, add, reset, commit
History -- inspect what you have now, and what happened before
log, blame, grep, show
Branching and Merging -- build and use alternate histories
branch, checkout -b, merge, rebase
Working with Others
remote, fetch, pull, push
with each of the command and the heading being a "link" (use ncurses for
that). If you choose the leaf-level command (say, 'diff'), you will get
the git-diff(1) manual page. If you pick one of the headings, say,
"Basic", you may get a more extended description of commands in the
category, that may include other basic commands not in the front page,
perhaps, like this:
(review)
diff HEAD: view what you did since the last commit
diff: view what you did since you last added
diff --cached: view what you already added
status: list what are added and changes yet to be added
(undo)
checkout path...: checkout a copy from the staging area
checkout HEAD path...: checkout a copy from the last commit
reset: undo earlier "git add" to the staging area
reset path...: do so only for the named paths
(record)
mv path1 path2: move the state of path1 to path2
rm path2: remove path2
rm --cached path2: do so without losing the copy in the working tree
add: add the contents to the staging area
add -p: do so interactively, hunk by hunk
commit: record the changes you added to the staging area
commit path...: record all the changes to the paths, ignoring
changes you added to the staging area for other paths.
and again each element can be a "link".
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
