On 05/07/2015 11:31 AM, Emma Jane Hogbin Westby wrote:
Sébastien !
This is fantastic! My apologies for jumping in late. Hopefully
I'm not too late.
Thank you :) It's just a very modest contribution though.
Sébastien Guimmara wrote:
This v4 includes the following suggestions:
In command-list.txt:
- Add a [groups] block containing names and description for groups:
[groups]
init starting a working area
worktree working on the current change
remote working with others
info examining the history and state
history growing, marking and tweaking your history
I like these headings / separation.
As you've already "lost" a line to the header, would it make sense to
add a "see also" into the Guides from here? For example:
starting a working area (see also: git help tutorial)
working on the current change (see also: git help everyday)
working with others (see also: git help workflows)
examining the history and state (see also: git help revisions)
I think it's a good idea.
[...]
This produces the following output of $ git help:
[...]
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 [...]
* working on the current change:
add Add file contents to the index
reset Reset current HEAD to the specified state
I could not live without status at this stage, and status always tells
me what I should do next. I'm tempted to see it up here instead...
The layout was not designed to be workflow oriented (even if it appears
so), but rather theme oriented. But I think that a redesign that
introduces the typical Git workflow in a gentle, not intimidating manner
could help beginners realize that Git is extremely simple in its core
principles.
* working with others:
fetch Download objects and refs from another repository
pull Fetch from and integrate with another repository [...]
push Update remote refs along with associated objects
* examining the history and state:
log Show commit logs
status Show the working tree status
For this grouping, instead of also having "state", I'd like to see log
and diff. Perhaps the header is simply "examining the history". This
narrowing would make more sense to then move status up to "working on
the current change".
* growing, marking and tweaking your history:
branch List, create, or delete branches
checkout Checkout a branch or paths to the working tree
commit Record changes to the repository
diff Show changes between commits, commit and working [...]
merge Join two or more development histories together
By the definition of "tweaking" I would include rebase. Hiding rebase
from the "common" list will increase its mystique and make people
even more hesitant to use it. Best to shine some light on it and help
to make it less scary. I would remove diff from this group as it is
a non-destructive command.
In a workflow-oriented 'git help', I believe this would make sense.
The patch originally started by examining what is really a 'common'
command, and I estimated that 'rebase' was not that common. However,
since 'rebase' is such a powerful tool and a killer feature of git
(among others), we could mention it in a way that is less intimidating
(see above)
What a wonderful thing to have started, Sébastien ! Thank you. :)
Thank you again :)
--
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