Sébastien Guimmara <sebastien.guimmara@xxxxxxxxx> writes: > We could then display headers this way: > > The most commonly used git commands are: > * starting a working area: > clone Clone a repository into a new directory > init Create an empty Git repository or reinitialize an existing one > * examining the history and state: > diff Show changes between commits, commit and working tree, etc > log Show commit logs > show Show various types of objects > status Show the working tree status > bisect Find by binary search the change that introduced a bug > grep Print lines matching a pattern > > * working on the current change: > add Add file contents to the index > checkout Checkout a branch or paths to the working tree > reset Reset current HEAD to the specified state > rm Remove files from the working tree and from the index > mv Move or rename a file, a directory, or a symlink > * growing, marking and tweaking your history: > commit Record changes to the repository > rebase Forward-port local commits to the updated upstream head > tag Create, list, delete or verify a tag object signed with GPG > * working with others: > fetch Download objects and refs from another repository > pull Fetch from and integrate with another repository or a local branch > push Update remote refs along with associated objects > * branching and merging histories: > branch List, create, or delete branches > merge Join two or more development histories together > > This raises a few questions: > > 1. Is 'bisect' really a common command (from the target audience standpoint) That is a good question, but so are many other commands. I think that (1) it is a good idea to list commands in groups, (2) having group-head is necessary if we list commands in groups, but (3) because group-heads consume valuable vertical space in the output, we may have to have fewer commands in the list. For example, "mv" and "rm" are very questionable things to have in the "most commonly used" list. All you need to start with Git is "add" and "commit -a". "clone" and "init" are "once per working area for a project you deal with" kind of thing, and cannot be in the "commonly used and you benefit from a gentle nudge to read about it more in the manual to learn Git" category by definition. "rebase" should be with "merge" and "branch", but I wouldn't have "branching and merging" as a separate category---they are all part of "growing and tweaking". And "branch" itself may be questionable for those who are starting with Git. Do we care about the ordering of the items within groups, by the way? > 2. Does 'Forward-port local commits to the updated upstream head' really help > to grok the idea of 'rebase' ? There are 3 words in this sentence that > an unfamiliar git user may not be comfortable with... "Rebuild the history on a branch on top of a new commit", perhaps? But this brings us back to "what the target audience?" question. My answer to the question has always been "the list is a gentle nudge to guide the user to read about it more in the manual to learn." The sooner users are guided to graduate from the "not be comfortable" state, the more productive they will be. For that to happen, we would need to (1) strongly suggest that the subcommand is what the user wants to use, and (2) carefully avoid giving an impression that the user learned everything there is to know in order to use the command effectively from that single line. Of course, an argument can be made that the single-line should aim to teach everything there is to know in order to use the command effectively, but because I do not think that is feasible I would aim for the second best, which is why we want to keep the last two lines about "git help <command> for a specific subcommand". -- 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