* [PATCH 0/3] git help: group common commands by theme
@ 2015-05-04 20:28 Sébastien Guimmara
2015-05-04 20:28 ` [PATCH 1/3] command-list.txt: " Sébastien Guimmara
` (6 more replies)
0 siblings, 7 replies; 38+ messages in thread
From: Sébastien Guimmara @ 2015-05-04 20:28 UTC (permalink / raw)
To: git; +Cc: Sébastien Guimmara, gitster, sunshine
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
- Add a [commands] header on top of the known command list, and
group names as a third column.
[commands]
git-add mainporcelain common-worktree
git-am mainporcelain
git-annotate ancillaryinterrogators
git-apply plumbingmanipulators
git-archimport foreignscminterface
git-archive mainporcelain
git-bisect mainporcelain
git-blame ancillaryinterrogators
git-branch mainporcelain common-history
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
* 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
* 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
[...]
I removed from the list of common commands: rebase, rm, mv, bisect
because [1] they are not really common to an unfamiliar user, [2] to
save vertical space occupied by group headers.
Thanks to Junio and Eric for their suggestions.
Sébastien Guimmara (3):
command-list.txt: group common commands by theme
generate-cmdlist.sh: parse common group commands
git help: group common commands by theme
command-list.txt | 64 +++++++++++++++++++++++++++++++----------------------
generate-cmdlist.sh | 43 +++++++++++++++++++++++++----------
help.c | 28 ++++++++++++++++++++++-
3 files changed, 95 insertions(+), 40 deletions(-)
--
2.4.0
^ permalink raw reply [flat|nested] 38+ messages in thread* [PATCH 1/3] command-list.txt: group common commands by theme 2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara @ 2015-05-04 20:28 ` Sébastien Guimmara 2015-05-06 6:57 ` Eric Sunshine 2015-05-04 20:28 ` [PATCH 2/3] generate-cmdlist.sh: parse common group commands Sébastien Guimmara ` (5 subsequent siblings) 6 siblings, 1 reply; 38+ messages in thread From: Sébastien Guimmara @ 2015-05-04 20:28 UTC (permalink / raw) To: git; +Cc: Sébastien Guimmara, gitster, sunshine Declare groups for common commands in the [groups] block, followed by group names and descriptions: [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 Then, in the [commands] block, map all common commands with a group: [commands] git-add mainporcelain common-worktree git-branch mainporcelain common-history git-checkout mainporcelain common-history [...] command names and groups are then parsed with generate-cmdlist.sh to generate common-commands.h. Those commands are displayed in groups in the output of 'git help'. Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com> --- command-list.txt | 64 ++++++++++++++++++++++++++++++++------------------------ 1 file changed, 37 insertions(+), 27 deletions(-) diff --git a/command-list.txt b/command-list.txt index f1eae08..64394ca 100644 --- a/command-list.txt +++ b/command-list.txt @@ -1,29 +1,39 @@ # List of known git commands. -# command name category [deprecated] [common] -git-add mainporcelain common +# only add group information for common commands + +[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 + +# command name [deprecated] category [group] +[commands] +git-add mainporcelain common-worktree git-am mainporcelain git-annotate ancillaryinterrogators git-apply plumbingmanipulators git-archimport foreignscminterface git-archive mainporcelain -git-bisect mainporcelain common +git-bisect mainporcelain git-blame ancillaryinterrogators -git-branch mainporcelain common +git-branch mainporcelain common-history git-bundle mainporcelain git-cat-file plumbinginterrogators git-check-attr purehelpers git-check-ignore purehelpers git-check-mailmap purehelpers -git-checkout mainporcelain common +git-checkout mainporcelain common-history git-checkout-index plumbingmanipulators git-check-ref-format purehelpers git-cherry ancillaryinterrogators git-cherry-pick mainporcelain git-citool mainporcelain git-clean mainporcelain -git-clone mainporcelain common +git-clone mainporcelain common-init git-column purehelpers -git-commit mainporcelain common +git-commit mainporcelain common-history git-commit-tree plumbingmanipulators git-config ancillarymanipulators git-count-objects ancillaryinterrogators @@ -35,42 +45,42 @@ git-cvsimport foreignscminterface git-cvsserver foreignscminterface git-daemon synchingrepositories git-describe mainporcelain -git-diff mainporcelain common +git-diff mainporcelain common-history git-diff-files plumbinginterrogators git-diff-index plumbinginterrogators git-diff-tree plumbinginterrogators git-difftool ancillaryinterrogators -git-fast-export ancillarymanipulators -git-fast-import ancillarymanipulators -git-fetch mainporcelain common +git-fast-export ancillarymanipulators +git-fast-import ancillarymanipulators +git-fetch mainporcelain common-remote git-fetch-pack synchingrepositories git-filter-branch ancillarymanipulators git-fmt-merge-msg purehelpers git-for-each-ref plumbinginterrogators git-format-patch mainporcelain -git-fsck ancillaryinterrogators +git-fsck ancillaryinterrogators git-gc mainporcelain git-get-tar-commit-id ancillaryinterrogators -git-grep mainporcelain common +git-grep mainporcelain git-gui mainporcelain git-hash-object plumbingmanipulators -git-help ancillaryinterrogators +git-help ancillaryinterrogators git-http-backend synchingrepositories git-http-fetch synchelpers git-http-push synchelpers git-imap-send foreignscminterface git-index-pack plumbingmanipulators -git-init mainporcelain common +git-init mainporcelain common-init git-instaweb ancillaryinterrogators git-interpret-trailers purehelpers gitk mainporcelain -git-log mainporcelain common +git-log mainporcelain common-info git-ls-files plumbinginterrogators git-ls-remote plumbinginterrogators git-ls-tree plumbinginterrogators git-mailinfo purehelpers git-mailsplit purehelpers -git-merge mainporcelain common +git-merge mainporcelain common-history git-merge-base plumbinginterrogators git-merge-file plumbingmanipulators git-merge-index plumbingmanipulators @@ -79,7 +89,7 @@ git-mergetool ancillarymanipulators git-merge-tree ancillaryinterrogators git-mktag plumbingmanipulators git-mktree plumbingmanipulators -git-mv mainporcelain common +git-mv mainporcelain git-name-rev plumbinginterrogators git-notes mainporcelain git-p4 foreignscminterface @@ -90,11 +100,11 @@ git-parse-remote synchelpers git-patch-id purehelpers git-prune ancillarymanipulators git-prune-packed plumbingmanipulators -git-pull mainporcelain common -git-push mainporcelain common +git-pull mainporcelain common-remote +git-push mainporcelain common-remote git-quiltimport foreignscminterface git-read-tree plumbingmanipulators -git-rebase mainporcelain common +git-rebase mainporcelain git-receive-pack synchelpers git-reflog ancillarymanipulators git-relink ancillarymanipulators @@ -103,28 +113,28 @@ git-repack ancillarymanipulators git-replace ancillarymanipulators git-request-pull foreignscminterface git-rerere ancillaryinterrogators -git-reset mainporcelain common +git-reset mainporcelain common-worktree git-revert mainporcelain git-rev-list plumbinginterrogators git-rev-parse ancillaryinterrogators -git-rm mainporcelain common +git-rm mainporcelain git-send-email foreignscminterface git-send-pack synchingrepositories git-shell synchelpers git-shortlog mainporcelain -git-show mainporcelain common +git-show mainporcelain git-show-branch ancillaryinterrogators git-show-index plumbinginterrogators git-show-ref plumbinginterrogators git-sh-i18n purehelpers git-sh-setup purehelpers git-stash mainporcelain -git-status mainporcelain common +git-status mainporcelain common-info git-stripspace purehelpers git-submodule mainporcelain git-svn foreignscminterface git-symbolic-ref plumbingmanipulators -git-tag mainporcelain common +git-tag mainporcelain git-unpack-file plumbinginterrogators git-unpack-objects plumbingmanipulators git-update-index plumbingmanipulators @@ -138,4 +148,4 @@ git-verify-pack plumbinginterrogators git-verify-tag ancillaryinterrogators gitweb ancillaryinterrogators git-whatchanged ancillaryinterrogators -git-write-tree plumbingmanipulators +git-write-tree plumbingmanipulators \ No newline at end of file -- 2.4.0 ^ permalink raw reply related [flat|nested] 38+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme 2015-05-04 20:28 ` [PATCH 1/3] command-list.txt: " Sébastien Guimmara @ 2015-05-06 6:57 ` Eric Sunshine 2015-05-06 20:58 ` Sébastien Guimmara 0 siblings, 1 reply; 38+ messages in thread From: Eric Sunshine @ 2015-05-06 6:57 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara <sebastien.guimmara@gmail.com> wrote: > Declare groups for common commands in the [groups] block, > followed by group names and descriptions: > > [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 > > Then, in the [commands] block, map all common commands with a group: > > [commands] > git-add mainporcelain common-worktree > git-branch mainporcelain common-history > git-checkout mainporcelain common-history > [...] > > command names and groups are then parsed with generate-cmdlist.sh to > generate common-commands.h. > > Those commands are displayed in groups in the output of 'git help'. It probably also is important to mention that the order of the items in [groups] is the order in which groups are output by 'git help' More below. > Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com> > --- > diff --git a/command-list.txt b/command-list.txt > index f1eae08..64394ca 100644 > --- a/command-list.txt > +++ b/command-list.txt > @@ -1,29 +1,39 @@ > # List of known git commands. > -# command name category [deprecated] [common] > -git-add mainporcelain common > +# only add group information for common commands Perhaps mention also that the order of groups here is the order in which they are output by 'git help'? > +[groups] Thinking on this a bit more, perhaps [groups] is too generic. Maybe [common] or [commongroups] would be more descriptive? > +init starting a working area > +worktree working on the current change > +remote working with others "collaborating with others" perhaps? More below. > +info examining the history and state > +history growing, marking and tweaking your history > + > +# command name [deprecated] category [group] > +[commands] > +git-add mainporcelain common-worktree > [...] > -git-bisect mainporcelain common > +git-bisect mainporcelain > [...] > -git-branch mainporcelain common > +git-branch mainporcelain common-history > [...] > -git-checkout mainporcelain common > +git-checkout mainporcelain common-history > [...] > -git-clone mainporcelain common > +git-clone mainporcelain common-init > [...] > -git-commit mainporcelain common > +git-commit mainporcelain common-history > [...] > -git-diff mainporcelain common > +git-diff mainporcelain common-history > [...] > -git-fast-export ancillarymanipulators > -git-fast-import ancillarymanipulators > -git-fetch mainporcelain common > +git-fast-export ancillarymanipulators > +git-fast-import ancillarymanipulators Unintended whitespace changes for fast-export and fast-import lines? I wouldn't have expected to see these lines change in this patch. > +git-fetch mainporcelain common-remote > [...] > -git-fsck ancillaryinterrogators > +git-fsck ancillaryinterrogators Unintended whitespace change? > [...] > -git-grep mainporcelain common > +git-grep mainporcelain This change isn't mentioned anywhere, not even in the cover letter. Did you intend to drop 'grep' from the common command list? > [...] > -git-help ancillaryinterrogators > +git-help ancillaryinterrogators Whitespace change? More below. > [...] > -git-init mainporcelain common > +git-init mainporcelain common-init > [...] > -git-log mainporcelain common > +git-log mainporcelain common-info > [...] > -git-merge mainporcelain common > +git-merge mainporcelain common-history > [...] > -git-mv mainporcelain common > +git-mv mainporcelain > [...] > -git-pull mainporcelain common > -git-push mainporcelain common > +git-pull mainporcelain common-remote > +git-push mainporcelain common-remote > [...] > -git-rebase mainporcelain common > +git-rebase mainporcelain > [...] > -git-reset mainporcelain common > +git-reset mainporcelain common-worktree > [...] > -git-rm mainporcelain common > +git-rm mainporcelain > [...] > -git-show mainporcelain common > +git-show mainporcelain > [...] > -git-status mainporcelain common > +git-status mainporcelain common-info > [...] > -git-tag mainporcelain common > +git-tag mainporcelain This change also is not mentioned anywhere. > [...] > -git-write-tree plumbingmanipulators > +git-write-tree plumbingmanipulators > \ No newline at end of file Your editor is perhaps dropping the final newline in the file? This is an undesirable change. Patch 2/3 exhibits the same problem. > -- > 2.4.0 ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme 2015-05-06 6:57 ` Eric Sunshine @ 2015-05-06 20:58 ` Sébastien Guimmara 2015-05-07 16:50 ` Eric Sunshine 0 siblings, 1 reply; 38+ messages in thread From: Sébastien Guimmara @ 2015-05-06 20:58 UTC (permalink / raw) To: Eric Sunshine; +Cc: Git List, Junio C Hamano, Sébastien Guimmara On 05/06/2015 08:57 AM, Eric Sunshine wrote: > On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara > <sebastien.guimmara@gmail.com> wrote: >> Declare groups for common commands in the [groups] block, >> followed by group names and descriptions: >> >> [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 >> >> Then, in the [commands] block, map all common commands with a group: >> >> [commands] >> git-add mainporcelain common-worktree >> git-branch mainporcelain common-history >> git-checkout mainporcelain common-history >> [...] >> >> command names and groups are then parsed with generate-cmdlist.sh to >> generate common-commands.h. >> >> Those commands are displayed in groups in the output of 'git help'. > > It probably also is important to mention that the order of the items > in [groups] is the order in which groups are output by 'git help' Yes. I'll add a comment in the file as well as in the commit. > > More below. > >> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com> >> --- >> diff --git a/command-list.txt b/command-list.txt >> index f1eae08..64394ca 100644 >> --- a/command-list.txt >> +++ b/command-list.txt >> @@ -1,29 +1,39 @@ >> # List of known git commands. >> -# command name category [deprecated] [common] >> -git-add mainporcelain common >> +# only add group information for common commands > > Perhaps mention also that the order of groups here is the order in > which they are output by 'git help'? It wouldn't be necessary if we reorder alphabetically the content of each group, no ? > >> +[groups] > > Thinking on this a bit more, perhaps [groups] is too generic. Maybe > [common] or [commongroups] would be more descriptive? > >> +init starting a working area >> +worktree working on the current change >> +remote working with others > > "collaborating with others" perhaps? Yes, "groups" has been itching a bit. I thought about "theme", but common just does the job too. "collaborating with others" sounds redundant to me (but I'm being a grammar nazi here). >> -git-fast-export ancillarymanipulators >> -git-fast-import ancillarymanipulators >> -git-fetch mainporcelain common >> +git-fast-export ancillarymanipulators >> +git-fast-import ancillarymanipulators > > Unintended whitespace changes for fast-export and fast-import lines? I > wouldn't have expected to see these lines change in this patch. > All whitespace changes were intended to align the commands on the same column. I realize this should be the object of a separate patch. >> -git-grep mainporcelain common >> +git-grep mainporcelain > > This change isn't mentioned anywhere, not even in the cover letter. > Did you intend to drop 'grep' from the common command list? It's a mistake in the cover letter. I indeed intended to propose to remove grep and tag from the common commands. >> [...] >> -git-write-tree plumbingmanipulators >> +git-write-tree plumbingmanipulators >> \ No newline at end of file > > Your editor is perhaps dropping the final newline in the file? This is > an undesirable change. Patch 2/3 exhibits the same problem. As for the final newline, it was deliberately removed. I was not aware it was necessary in text files. I'll correct this. Thank you for the help, Sébastien ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme 2015-05-06 20:58 ` Sébastien Guimmara @ 2015-05-07 16:50 ` Eric Sunshine 2015-05-07 19:23 ` Johannes Sixt 2015-05-08 18:43 ` Sébastien Guimmara 0 siblings, 2 replies; 38+ messages in thread From: Eric Sunshine @ 2015-05-07 16:50 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano On Wed, May 6, 2015 at 4:58 PM, Sébastien Guimmara <sebastien.guimmara@gmail.com> wrote: > On 05/06/2015 08:57 AM, Eric Sunshine wrote: >> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara >> <sebastien.guimmara@gmail.com> wrote: >>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com> >>> --- >>> diff --git a/command-list.txt b/command-list.txt >>> index f1eae08..64394ca 100644 >>> --- a/command-list.txt >>> +++ b/command-list.txt >>> @@ -1,29 +1,39 @@ >>> # List of known git commands. >>> -# command name category [deprecated] [common] >>> -git-add mainporcelain common >>> +# only add group information for common commands >> >> Perhaps mention also that the order of groups here is the order in >> which they are output by 'git help'? > > It wouldn't be necessary if we reorder alphabetically the content of > each group, no ? I'm not sure to what you are referring here? (Perhaps my comment was unclear, or perhaps I'm misreading your response.) I meant only that the comment above [groups] should say that the order of the items in [groups] is the order in which the groups themselves are output by "git help". >>> +[groups] >> >> Thinking on this a bit more, perhaps [groups] is too generic. Maybe >> [common] or [commongroups] would be more descriptive? >> >>> +init starting a working area >>> +worktree working on the current change >>> +remote working with others >> >> "collaborating with others" perhaps? > > Yes, "groups" has been itching a bit. I thought about "theme", but > common just does the job too. "collaborating with others" sounds > redundant to me (but I'm being a grammar nazi here). I also think "collaborating" itself is best, but changed it at the last second before sending the email. >>> -git-fast-export ancillarymanipulators >>> -git-fast-import ancillarymanipulators >>> -git-fetch mainporcelain common >>> +git-fast-export ancillarymanipulators >>> +git-fast-import ancillarymanipulators >> >> Unintended whitespace changes for fast-export and fast-import lines? I >> wouldn't have expected to see these lines change in this patch. > > All whitespace changes were intended to align the commands on the same > column. I realize this should be the object of a separate patch. Strange. In my editor, all columns are already aligned. Perhaps your tab with setting is incorrect? (It should be set to 8.) >>> -git-grep mainporcelain common >>> +git-grep mainporcelain >> >> This change isn't mentioned anywhere, not even in the cover letter. >> Did you intend to drop 'grep' from the common command list? > > It's a mistake in the cover letter. I indeed intended to propose to > remove grep and tag from the common commands. I personally consider "grep" an important beginner command, but that's an issue to be argued separately; and it's also why it's a good idea to put the removals in their own patch, so people can argue about it without holding up the rest of the patches. >>> [...] >>> -git-write-tree plumbingmanipulators >>> +git-write-tree plumbingmanipulators >>> \ No newline at end of file >> >> Your editor is perhaps dropping the final newline in the file? This is >> an undesirable change. Patch 2/3 exhibits the same problem. > > As for the final newline, it was deliberately removed. I was not aware it > was necessary in text files. I'll correct this. Historically, many Unix tools incorrectly handled files lacking that final newline; sometimes by dropping the line altogether, sometimes mis-processing it in some way or another. Misbehaviors still exist today, often in BSD tools. In fact, just a few days ago, such a problem was reported for git-filter-branch[1]. Consequently, retaining newline is good insurance against misbehaving tools. [1]: http://thread.gmane.org/gmane.comp.version-control.git/267828/focus=267957 ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme 2015-05-07 16:50 ` Eric Sunshine @ 2015-05-07 19:23 ` Johannes Sixt 2015-05-08 10:11 ` Johannes Schindelin 2015-05-08 18:43 ` Sébastien Guimmara 1 sibling, 1 reply; 38+ messages in thread From: Johannes Sixt @ 2015-05-07 19:23 UTC (permalink / raw) To: Eric Sunshine, Sébastien Guimmara; +Cc: Git List, Junio C Hamano Am 07.05.2015 um 18:50 schrieb Eric Sunshine: > On Wed, May 6, 2015 at 4:58 PM, Sébastien Guimmara > <sebastien.guimmara@gmail.com> wrote: >> On 05/06/2015 08:57 AM, Eric Sunshine wrote: >>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara >>> <sebastien.guimmara@gmail.com> wrote: >>>> -git-write-tree plumbingmanipulators >>>> +git-write-tree plumbingmanipulators >>>> \ No newline at end of file >>> >>> Your editor is perhaps dropping the final newline in the file? This is >>> an undesirable change. Patch 2/3 exhibits the same problem. >> >> As for the final newline, it was deliberately removed. I was not aware it >> was necessary in text files. I'll correct this. > > Historically, many Unix tools incorrectly handled files lacking that > final newline; sometimes by dropping the line altogether, sometimes > mis-processing it in some way or another. Misbehaviors still exist > today, often in BSD tools. In fact, just a few days ago, such a > problem was reported for git-filter-branch[1]. Consequently, retaining > newline is good insurance against misbehaving tools. Files lacking the trailing new-line are not "text files" according to the POSIX definition, BTW. -- Hannes ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme 2015-05-07 19:23 ` Johannes Sixt @ 2015-05-08 10:11 ` Johannes Schindelin 2015-05-08 12:01 ` Andreas Schwab 0 siblings, 1 reply; 38+ messages in thread From: Johannes Schindelin @ 2015-05-08 10:11 UTC (permalink / raw) To: Johannes Sixt; +Cc: Sébastien Guimmara, Git List, Junio C Hamano Hi Hannes, On 2015-05-07 21:23, Johannes Sixt wrote: > Files lacking the trailing new-line are not "text files" according to > the POSIX definition, BTW. It's probably my failure for not finding the documentation on that, but I really would like to be educated. Do you have an authoritative source for that statement? Thank you, Johannes P.S.: Somehow when I ask GMX to send mail to Eric Sunshine today, it refuses ("mailbox not available"?), so I removed the address from the Cc: list. Will investigate what is wrong if that happens again. Sorry! ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme 2015-05-08 10:11 ` Johannes Schindelin @ 2015-05-08 12:01 ` Andreas Schwab 2015-05-08 13:02 ` Johannes Schindelin 0 siblings, 1 reply; 38+ messages in thread From: Andreas Schwab @ 2015-05-08 12:01 UTC (permalink / raw) To: Johannes Schindelin Cc: Johannes Sixt, Sébastien Guimmara, Git List, Junio C Hamano Johannes Schindelin <johannes.schindelin@gmx.de> writes: > It's probably my failure for not finding the documentation on that, but I really would like to be educated. Do you have an authoritative source for that statement? http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html 3.206 Line A sequence of zero or more non- <newline> characters plus a terminating <newline> character. 3.397 Text File A file that contains characters organized into zero or more lines. The lines do not contain NUL characters and none can exceed {LINE_MAX} bytes in length, including the <newline> character. Although POSIX.1-2008 does not distinguish between text files and binary files (see the ISO C standard), many utilities only produce predictable or meaningful output when operating on text files. The standard utilities that have such restrictions always specify "text files" in their STDIN or INPUT FILES sections. Andreas. -- Andreas Schwab, schwab@linux-m68k.org GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different." ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme 2015-05-08 12:01 ` Andreas Schwab @ 2015-05-08 13:02 ` Johannes Schindelin 0 siblings, 0 replies; 38+ messages in thread From: Johannes Schindelin @ 2015-05-08 13:02 UTC (permalink / raw) To: Andreas Schwab Cc: Johannes Sixt, Sébastien Guimmara, Git List, Junio C Hamano Hi Andreas, On 2015-05-08 14:01, Andreas Schwab wrote: > Johannes Schindelin <johannes.schindelin@gmx.de> writes: > >> It's probably my failure for not finding the documentation on that, but I really would like to be educated. Do you have an authoritative source for that statement? > > http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html > > 3.206 Line > A sequence of zero or more non- <newline> characters plus a terminating > <newline> character. > > 3.397 Text File > A file that contains characters organized into zero or more lines. The > lines do not contain NUL characters and none can exceed {LINE_MAX} bytes > in length, including the <newline> character. Although POSIX.1-2008 does > not distinguish between text files and binary files (see the ISO C > standard), many utilities only produce predictable or meaningful output > when operating on text files. The standard utilities that have such > restrictions always specify "text files" in their STDIN or INPUT FILES > sections. Thanks! Dscho ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme 2015-05-07 16:50 ` Eric Sunshine 2015-05-07 19:23 ` Johannes Sixt @ 2015-05-08 18:43 ` Sébastien Guimmara 2015-05-08 19:00 ` Eric Sunshine 1 sibling, 1 reply; 38+ messages in thread From: Sébastien Guimmara @ 2015-05-08 18:43 UTC (permalink / raw) To: Eric Sunshine, Git Users On 05/07/2015 06:50 PM, Eric Sunshine wrote: > On Wed, May 6, 2015 at 4:58 PM, Sébastien Guimmara > <sebastien.guimmara@gmail.com> wrote: >> On 05/06/2015 08:57 AM, Eric Sunshine wrote: >>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara >>> <sebastien.guimmara@gmail.com> wrote: >>>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com> >>>> --- >>>> diff --git a/command-list.txt b/command-list.txt >>>> index f1eae08..64394ca 100644 >>>> --- a/command-list.txt >>>> +++ b/command-list.txt >>>> @@ -1,29 +1,39 @@ >>>> # List of known git commands. >>>> -# command name category [deprecated] [common] >>>> -git-add mainporcelain common >>>> +# only add group information for common commands >>> >>> Perhaps mention also that the order of groups here is the order in >>> which they are output by 'git help'? >> >> It wouldn't be necessary if we reorder alphabetically the content of >> each group, no ? > > I'm not sure to what you are referring here? (Perhaps my comment was > unclear, or perhaps I'm misreading your response.) > I was mistaken, I thought you wanted to reorder the commands alphabetically, which was unnecessary since they were sorted in help.c anyway. But yes, I shall add a comment in command-list.txt > I meant only that the comment above [groups] should say that the order > of the items in [groups] is the order in which the groups themselves > are output by "git help". > >>>> +[groups] >>> >>> Thinking on this a bit more, perhaps [groups] is too generic. Maybe >>> [common] or [commongroups] would be more descriptive? >>> >>>> +init starting a working area >>>> +worktree working on the current change >>>> +remote working with others >>> >>> "collaborating with others" perhaps? >> >> Yes, "groups" has been itching a bit. I thought about "theme", but >> common just does the job too. "collaborating with others" sounds >> redundant to me (but I'm being a grammar nazi here). > > I also think "collaborating" itself is best, but changed it at the > last second before sending the email. > >>>> -git-fast-export ancillarymanipulators >>>> -git-fast-import ancillarymanipulators >>>> -git-fetch mainporcelain common >>>> +git-fast-export ancillarymanipulators >>>> +git-fast-import ancillarymanipulators >>> >>> Unintended whitespace changes for fast-export and fast-import lines? I >>> wouldn't have expected to see these lines change in this patch. >> >> All whitespace changes were intended to align the commands on the same >> column. I realize this should be the object of a separate patch. > > Strange. In my editor, all columns are already aligned. Perhaps your > tab with setting is incorrect? (It should be set to 8.) > Actually I only removed the few tabs that were wandering in some lines to replace them by spaces (almost all lines were space aligned, only a few were tab aligned). >>>> -git-grep mainporcelain common >>>> +git-grep mainporcelain >>> >>> This change isn't mentioned anywhere, not even in the cover letter. >>> Did you intend to drop 'grep' from the common command list? >> >> It's a mistake in the cover letter. I indeed intended to propose to >> remove grep and tag from the common commands. > > I personally consider "grep" an important beginner command, but that's > an issue to be argued separately; and it's also why it's a good idea > to put the removals in their own patch, so people can argue about it > without holding up the rest of the patches. > >>>> [...] >>>> -git-write-tree plumbingmanipulators >>>> +git-write-tree plumbingmanipulators >>>> \ No newline at end of file >>> >>> Your editor is perhaps dropping the final newline in the file? This is >>> an undesirable change. Patch 2/3 exhibits the same problem. >> >> As for the final newline, it was deliberately removed. I was not aware it >> was necessary in text files. I'll correct this. > > Historically, many Unix tools incorrectly handled files lacking that > final newline; sometimes by dropping the line altogether, sometimes > mis-processing it in some way or another. Misbehaviors still exist > today, often in BSD tools. In fact, just a few days ago, such a > problem was reported for git-filter-branch[1]. Consequently, retaining > newline is good insurance against misbehaving tools. > > [1]: http://thread.gmane.org/gmane.comp.version-control.git/267828/focus=267957 > ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 1/3] command-list.txt: group common commands by theme 2015-05-08 18:43 ` Sébastien Guimmara @ 2015-05-08 19:00 ` Eric Sunshine 0 siblings, 0 replies; 38+ messages in thread From: Eric Sunshine @ 2015-05-08 19:00 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: Git Users On Fri, May 8, 2015 at 2:43 PM, Sébastien Guimmara <sebastien.guimmara@gmail.com> wrote: > On 05/07/2015 06:50 PM, Eric Sunshine wrote: >> On Wed, May 6, 2015 at 4:58 PM, Sébastien Guimmara >> <sebastien.guimmara@gmail.com> wrote: >>> On 05/06/2015 08:57 AM, Eric Sunshine wrote: >>>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara >>>> <sebastien.guimmara@gmail.com> wrote: >>>>> -git-fast-export ancillarymanipulators >>>>> -git-fast-import ancillarymanipulators >>>>> -git-fetch mainporcelain common >>>>> +git-fast-export ancillarymanipulators >>>>> +git-fast-import ancillarymanipulators >>>> >>>> Unintended whitespace changes for fast-export and fast-import lines? I >>>> wouldn't have expected to see these lines change in this patch. >>> >>> All whitespace changes were intended to align the commands on the same >>> column. I realize this should be the object of a separate patch. >> >> Strange. In my editor, all columns are already aligned. Perhaps your >> tab with setting is incorrect? (It should be set to 8.) > > Actually I only removed the few tabs that were wandering in some lines > to replace them by spaces (almost all lines were space aligned, only a few > were tab aligned). Ah, I see. Thanks for the explanation. ^ permalink raw reply [flat|nested] 38+ messages in thread
* [PATCH 2/3] generate-cmdlist.sh: parse common group commands 2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara 2015-05-04 20:28 ` [PATCH 1/3] command-list.txt: " Sébastien Guimmara @ 2015-05-04 20:28 ` Sébastien Guimmara 2015-05-08 3:20 ` Eric Sunshine 2015-05-04 20:28 ` [PATCH 3/3] git help: group common commands by theme Sébastien Guimmara ` (4 subsequent siblings) 6 siblings, 1 reply; 38+ messages in thread From: Sébastien Guimmara @ 2015-05-04 20:28 UTC (permalink / raw) To: git; +Cc: Sébastien Guimmara, gitster, sunshine parse the [groups] block to create the array of group descriptions static char *common_cmd_groups[] = { N_("starting a working area"), N_("working on the current change"), N_("working with others"), N_("examining the history and state"), N_("growing, marking and tweaking your history"), }; then map each element of common_cmds[] to a group via its index: static struct cmdname_help common_cmds[] = { {"add", N_("Add file contents to the index"), 1}, {"branch", N_("List, create, or delete branches"), 4}, {"checkout", N_("Checkout a branch or paths to the working tree"), 4}, {"clone", N_("Clone a repository into a new directory"), 0}, {"commit", N_("Record changes to the repository"), 4}, [...] So that 'git help' can print those command grouped by theme. Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com> --- generate-cmdlist.sh | 43 +++++++++++++++++++++++++++++++------------ 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh index 9a4c9b9..724bb8d 100755 --- a/generate-cmdlist.sh +++ b/generate-cmdlist.sh @@ -1,23 +1,42 @@ #!/bin/sh +content=$(cat command-list.txt) + +group_line_no=$(expr $(echo "$content" | grep -n '^\[groups\]' | cut -f1 -d:) + 1) +command_line_no=$(expr $(echo "$content" | grep -n '^\[commands\]' | cut -f1 -d:) + 1) +groups=$(echo "$content" | sed -n ''$group_line_no', '$(expr $command_line_no)'p') echo "/* Automatically generated by $0 */ + struct cmdname_help { char name[16]; char help[80]; + unsigned char group; }; +static char *common_cmd_groups[] = {" +echo "$groups" | +while read group description; do + if [ -z $group ]; then + break + fi + echo ' N_("'$description'"),' +done +echo "}; + static struct cmdname_help common_cmds[] = {" -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' command-list.txt | -sort | -while read cmd -do - sed -n ' - /^NAME/,/git-'"$cmd"'/H - ${ - x - s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", N_("\1")},/ - p - }' "Documentation/git-$cmd.txt" +echo "$content" | grep 'common-' | +awk '{ print $1, "\t", $3 }' | +while read cmd grp; do + cmd_name=$(echo $cmd | cut -d - -f 2) + group_name=$(echo $grp | cut -d - -f 2) + group_idx=$(expr $(echo "$groups" | grep -n "^$group_name" | cut -c 1) - 1) + sed -n ' + /^NAME/,/git-'"$cmd_name"'/H + ${ + x + s/.*git-'"$cmd_name"' - \(.*\)/ {"'"$cmd_name"'", N_("\1"), '"$group_idx"'},/ + p + }' "Documentation/$cmd.txt" done -echo "};" +echo "};" \ No newline at end of file -- 2.4.0 ^ permalink raw reply related [flat|nested] 38+ messages in thread
* Re: [PATCH 2/3] generate-cmdlist.sh: parse common group commands 2015-05-04 20:28 ` [PATCH 2/3] generate-cmdlist.sh: parse common group commands Sébastien Guimmara @ 2015-05-08 3:20 ` Eric Sunshine 2015-05-08 3:39 ` Eric Sunshine 2015-05-08 20:55 ` Sébastien Guimmara 0 siblings, 2 replies; 38+ messages in thread From: Eric Sunshine @ 2015-05-08 3:20 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: git, gitster On Mon, May 04, 2015 at 10:28:09PM +0200, Sébastien Guimmara wrote: > parse the [groups] block to create the array of group descriptions > > static char *common_cmd_groups[] = { > N_("starting a working area"), > ... > }; > > then map each element of common_cmds[] to a group via its index: > > static struct cmdname_help common_cmds[] = { > {"add", N_("Add file contents to the index"), 1}, > ... > > So that 'git help' can print those command grouped by theme. > --- > diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh > @@ -1,23 +1,42 @@ > +content=$(cat command-list.txt) > + > +group_line_no=$(expr $(echo "$content" | grep -n '^\[groups\]' | cut -f1 -d:) + 1) > +command_line_no=$(expr $(echo "$content" | grep -n '^\[commands\]' | cut -f1 -d:) + 1) > +groups=$(echo "$content" | sed -n ''$group_line_no', '$(expr $command_line_no)'p') > [...] > +static char *common_cmd_groups[] = {" > +echo "$groups" | > +while read group description; do > + if [ -z $group ]; then > + break > + fi > + echo ' N_("'$description'"),' > +done > +echo "}; > [...] > +echo "$content" | grep 'common-' | > +awk '{ print $1, "\t", $3 }' | > +while read cmd grp; do > + cmd_name=$(echo $cmd | cut -d - -f 2) > + group_name=$(echo $grp | cut -d - -f 2) > + group_idx=$(expr $(echo "$groups" | grep -n "^$group_name" | cut -c 1) - 1) > + sed -n ' > + /^NAME/,/git-'"$cmd_name"'/H > + ${ > + x > + s/.*git-'"$cmd_name"' - \(.*\)/ {"'"$cmd_name"'", N_("\1"), '"$group_idx"'},/ > + p > + }' "Documentation/$cmd.txt" Background: In an earlier review, I observed[1] that the "common-" in the "common-N_group" form was redundant, and I suggested that you could add a [groups] section listing the groups, and that the order of items in [groups] would imply the "git help" display order of the groups, thus allowing you to do away with the "N_" qualifier, as well. I also observed that you could determine if a command in [commands] was common by checking if it was tagged with an attribute from [groups], thus alleviating the need for the "common-" prefix. This round makes nice headway toward the proposed scheme, although it still depends upon the redundant "common-" prefix. When I earlier suggested that awk could be helpful[2], I was thinking of its associative arrays which could be used to determine if a command in [commands] was tagged with an attribute from [groups]. I had intended to reply to the current patch with a short "here's what I had in mind" example of using awk to achieve this goal, however, the short example ended up implementing the full functionality, so I went ahead and turned it into a proper patch[6] (below), and shamelessly re-used your commit message (with minor changes). You're welcome to include this patch in your re-roll, or use it as inspiration if you want to write the functionality yourself. Some notes about the re-implementation in awk: It assumes that [groups] has been renamed to [common] as suggested[3], and assumes that the "common-" prefix has been dropped from the [commands] attribute entries. The awk script replaces the current shell script entirely, and all common-cmds.h generation functionality is now handled by the one awk invocation rather than by a series of commands invoked by the shell script, which should make it faster (especially on Windows). Finally, unlike the shell script, the awk script does not bother sorting commands from command-list.txt since it assumes that command sorting will happen in parallel with grouping[4]. When the awk script encounters [common], it begins collecting group names in a grp[] array and emits the appropriate common_cmd_groups[] "C" initializer for each. Upon encountering [commands], it switches mode and, for each command line, checks if any attribute with which a command is tagged exists in grp[]. If so, it emits the appropriate common_cmds[] "C" initializer. Comment and blank lines are skipped. By the way, Junio observed[5] that you will need to adjust a couple Makefiles (and such) to account for the new [common] section and [commands] header. A good start would be to filter command-list.txt via this command: sed '1,/\[commands\]/d' <command-list.txt which will strip out everything up to and including the [commands] header. [1]: http://article.gmane.org/gmane.comp.version-control.git/268291 [2]: http://article.gmane.org/gmane.comp.version-control.git/268294 [3]: http://article.gmane.org/gmane.comp.version-control.git/268453 [4]: http://article.gmane.org/gmane.comp.version-control.git/268442 [5]: http://article.gmane.org/gmane.comp.version-control.git/268443 [6]: Below is full patch which replaces 2/3 from this round: --- >8 --- From: Eric Sunshine <sunshine@sunshineco.com> Subject: [PATCH] generate-cmdlist: parse common group commands Parse the [common] block to create the array of group descriptions: static char *common_cmd_groups[] = { N_("starting a working area"), N_("working on the current change"), N_("working with others"), N_("examining the history and state"), N_("growing, marking and tweaking your history"), }; then map each element of common_cmds[] to a group via its index: static struct cmdname_help common_cmds[] = { {"add", N_("Add file contents to the index"), 1}, {"branch", N_("List, create, or delete branches"), 4}, {"checkout", N_("Checkout a branch or paths to the ..."), 4}, {"clone", N_("Clone a repository into a new directory"), 0}, {"commit", N_("Record changes to the repository"), 4}, ... }; so that 'git help' can print those commands grouped by theme. Only commands tagged with an attribute from [common] are emitted to common_cmds[]. [commit message by Sébastien Guimmara <sebastien.guimmara@gmail.com>] Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> --- Makefile | 4 ++-- generate-cmdlist.awk | 39 +++++++++++++++++++++++++++++++++++++++ generate-cmdlist.sh | 23 ----------------------- 3 files changed, 41 insertions(+), 25 deletions(-) create mode 100644 generate-cmdlist.awk delete mode 100755 generate-cmdlist.sh diff --git a/Makefile b/Makefile index 5f3987f..de28ae1 100644 --- a/Makefile +++ b/Makefile @@ -1687,10 +1687,10 @@ $(BUILT_INS): git$X ln -s $< $@ 2>/dev/null || \ cp $< $@ -common-cmds.h: ./generate-cmdlist.sh command-list.txt +common-cmds.h: generate-cmdlist.awk command-list.txt common-cmds.h: $(wildcard Documentation/git-*.txt) - $(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@ + $(QUIET_GEN)awk -f generate-cmdlist.awk command-list.txt > $@+ && mv $@+ $@ SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\ $(localedir_SQ):$(NO_CURL):$(USE_GETTEXT_SCHEME):$(SANE_TOOL_PATH_SQ):\ diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk new file mode 100644 index 0000000..19b36e5 --- /dev/null +++ b/generate-cmdlist.awk @@ -0,0 +1,39 @@ +BEGIN { + print "/* Automatically generated */\n" + print "struct cmdname_help {" + print "\tchar name[16];" + print "\tchar help[80];" + print "\tunsigned char group;" + print "};\n" + print "static char *common_cmd_groups[] = {" +} +/^#/ || /^[ ]*$/ { next } +state == 2 { + for (i = 2; i <= NF; i++) + if (grp[$i]) { + f = "Documentation/"$1".txt" + while (getline s <f > 0) + if (match(s, $1" - ")) { + t = substr(s, length($1" - ") + 1) + break + } + close(f) + printf "\t{\"%s\", N_(\"%s\"), %s},\n", + substr($1, length("git-") + 1), t, grp[$i] - 1 + break + } +} +/\[commands\]/ { + print "};\n\nstatic struct cmdname_help common_cmds[] = {" + state = 2 +} +state == 1 { + grp[$1] = ++n + sub($1"[ ][ ]*", "") + printf "\tN_(\"%s\"),\n", $0 + next +} +/\[common\]/ { + state = 1 +} +END { print "};" } diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh deleted file mode 100755 index 9a4c9b9..0000000 --- a/generate-cmdlist.sh +++ /dev/null @@ -1,23 +0,0 @@ -#!/bin/sh - -echo "/* Automatically generated by $0 */ -struct cmdname_help { - char name[16]; - char help[80]; -}; - -static struct cmdname_help common_cmds[] = {" - -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' command-list.txt | -sort | -while read cmd -do - sed -n ' - /^NAME/,/git-'"$cmd"'/H - ${ - x - s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", N_("\1")},/ - p - }' "Documentation/git-$cmd.txt" -done -echo "};" -- 2.4.0.319.g7a04823 --- >8 --- ^ permalink raw reply related [flat|nested] 38+ messages in thread
* Re: [PATCH 2/3] generate-cmdlist.sh: parse common group commands 2015-05-08 3:20 ` Eric Sunshine @ 2015-05-08 3:39 ` Eric Sunshine 2015-05-08 20:55 ` Sébastien Guimmara 1 sibling, 0 replies; 38+ messages in thread From: Eric Sunshine @ 2015-05-08 3:39 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano On Thu, May 7, 2015 at 11:20 PM, Eric Sunshine <sunshine@sunshineco.com> wrote: > From: Eric Sunshine <sunshine@sunshineco.com> > Subject: [PATCH] generate-cmdlist: parse common group commands > > Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> > --- > diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk > new file mode 100644 > index 0000000..19b36e5 > --- /dev/null > +++ b/generate-cmdlist.awk > @@ -0,0 +1,39 @@ > [...] > +state == 1 { > + grp[$1] = ++n > + sub($1"[ ][ ]*", "") > + printf "\tN_(\"%s\"),\n", $0 > + next By the way, this 'next' line can be deleted. It was leftover gunk from an earlier iteration. It doesn't harm, but doesn't help either, and is thus potentially confusing. > +} > +/\[common\]/ { > + state = 1 > +} > +END { print "};" } ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 2/3] generate-cmdlist.sh: parse common group commands 2015-05-08 3:20 ` Eric Sunshine 2015-05-08 3:39 ` Eric Sunshine @ 2015-05-08 20:55 ` Sébastien Guimmara 1 sibling, 0 replies; 38+ messages in thread From: Sébastien Guimmara @ 2015-05-08 20:55 UTC (permalink / raw) To: Eric Sunshine; +Cc: git, gitster On 05/08/2015 05:20 AM, Eric Sunshine wrote: > On Mon, May 04, 2015 at 10:28:09PM +0200, Sébastien Guimmara wrote: >> parse the [groups] block to create the array of group descriptions >> >> static char *common_cmd_groups[] = { >> N_("starting a working area"), >> ... >> }; >> >> then map each element of common_cmds[] to a group via its index: >> >> static struct cmdname_help common_cmds[] = { >> {"add", N_("Add file contents to the index"), 1}, >> ... >> >> So that 'git help' can print those command grouped by theme. >> --- >> diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh >> @@ -1,23 +1,42 @@ >> +content=$(cat command-list.txt) >> + >> +group_line_no=$(expr $(echo "$content" | grep -n '^\[groups\]' | cut -f1 -d:) + 1) >> +command_line_no=$(expr $(echo "$content" | grep -n '^\[commands\]' | cut -f1 -d:) + 1) >> +groups=$(echo "$content" | sed -n ''$group_line_no', '$(expr $command_line_no)'p') >> [...] >> +static char *common_cmd_groups[] = {" >> +echo "$groups" | >> +while read group description; do >> + if [ -z $group ]; then >> + break >> + fi >> + echo ' N_("'$description'"),' >> +done >> +echo "}; >> [...] >> +echo "$content" | grep 'common-' | >> +awk '{ print $1, "\t", $3 }' | >> +while read cmd grp; do >> + cmd_name=$(echo $cmd | cut -d - -f 2) >> + group_name=$(echo $grp | cut -d - -f 2) >> + group_idx=$(expr $(echo "$groups" | grep -n "^$group_name" | cut -c 1) - 1) >> + sed -n ' >> + /^NAME/,/git-'"$cmd_name"'/H >> + ${ >> + x >> + s/.*git-'"$cmd_name"' - \(.*\)/ {"'"$cmd_name"'", N_("\1"), '"$group_idx"'},/ >> + p >> + }' "Documentation/$cmd.txt" > > Background: In an earlier review, I observed[1] that the "common-" in > the "common-N_group" form was redundant, and I suggested that you > could add a [groups] section listing the groups, and that the order > of items in [groups] would imply the "git help" display order of the > groups, thus allowing you to do away with the "N_" qualifier, as > well. I also observed that you could determine if a command in > [commands] was common by checking if it was tagged with an attribute > from [groups], thus alleviating the need for the "common-" prefix. > > This round makes nice headway toward the proposed scheme, although it > still depends upon the redundant "common-" prefix. When I earlier > suggested that awk could be helpful[2], I was thinking of its > associative arrays which could be used to determine if a command in > [commands] was tagged with an attribute from [groups]. > > I had intended to reply to the current patch with a short "here's > what I had in mind" example of using awk to achieve this goal, > however, the short example ended up implementing the full > functionality, so I went ahead and turned it into a proper patch[6] > (below), and shamelessly re-used your commit message (with minor > changes). You're welcome to include this patch in your re-roll, or > use it as inspiration if you want to write the functionality > yourself. > > Some notes about the re-implementation in awk: It assumes that > [groups] has been renamed to [common] as suggested[3], and assumes > that the "common-" prefix has been dropped from the [commands] > attribute entries. The awk script replaces the current shell script > entirely, and all common-cmds.h generation functionality is now > handled by the one awk invocation rather than by a series of commands > invoked by the shell script, which should make it faster (especially > on Windows). Finally, unlike the shell script, the awk script does > not bother sorting commands from command-list.txt since it assumes > that command sorting will happen in parallel with grouping[4]. > > When the awk script encounters [common], it begins collecting group > names in a grp[] array and emits the appropriate common_cmd_groups[] > "C" initializer for each. Upon encountering [commands], it switches > mode and, for each command line, checks if any attribute with which a > command is tagged exists in grp[]. If so, it emits the appropriate > common_cmds[] "C" initializer. Comment and blank lines are skipped. > > By the way, Junio observed[5] that you will need to adjust a couple > Makefiles (and such) to account for the new [common] section and > [commands] header. A good start would be to filter command-list.txt > via this command: > > sed '1,/\[commands\]/d' <command-list.txt > > which will strip out everything up to and including the [commands] > header. > > [1]: http://article.gmane.org/gmane.comp.version-control.git/268291 > [2]: http://article.gmane.org/gmane.comp.version-control.git/268294 > [3]: http://article.gmane.org/gmane.comp.version-control.git/268453 > [4]: http://article.gmane.org/gmane.comp.version-control.git/268442 > [5]: http://article.gmane.org/gmane.comp.version-control.git/268443 > [6]: Below is full patch which replaces 2/3 from this round: > > --- >8 --- > From: Eric Sunshine <sunshine@sunshineco.com> > Subject: [PATCH] generate-cmdlist: parse common group commands > > Parse the [common] block to create the array of group descriptions: > > static char *common_cmd_groups[] = { > N_("starting a working area"), > N_("working on the current change"), > N_("working with others"), > N_("examining the history and state"), > N_("growing, marking and tweaking your history"), > }; > > then map each element of common_cmds[] to a group via its index: > > static struct cmdname_help common_cmds[] = { > {"add", N_("Add file contents to the index"), 1}, > {"branch", N_("List, create, or delete branches"), 4}, > {"checkout", N_("Checkout a branch or paths to the ..."), 4}, > {"clone", N_("Clone a repository into a new directory"), 0}, > {"commit", N_("Record changes to the repository"), 4}, > ... > }; > > so that 'git help' can print those commands grouped by theme. > > Only commands tagged with an attribute from [common] are emitted to > common_cmds[]. > > [commit message by Sébastien Guimmara <sebastien.guimmara@gmail.com>] > > Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> > --- > Makefile | 4 ++-- > generate-cmdlist.awk | 39 +++++++++++++++++++++++++++++++++++++++ > generate-cmdlist.sh | 23 ----------------------- > 3 files changed, 41 insertions(+), 25 deletions(-) > create mode 100644 generate-cmdlist.awk > delete mode 100755 generate-cmdlist.sh > > diff --git a/Makefile b/Makefile > index 5f3987f..de28ae1 100644 > --- a/Makefile > +++ b/Makefile > @@ -1687,10 +1687,10 @@ $(BUILT_INS): git$X > ln -s $< $@ 2>/dev/null || \ > cp $< $@ > > -common-cmds.h: ./generate-cmdlist.sh command-list.txt > +common-cmds.h: generate-cmdlist.awk command-list.txt > > common-cmds.h: $(wildcard Documentation/git-*.txt) > - $(QUIET_GEN)./generate-cmdlist.sh > $@+ && mv $@+ $@ > + $(QUIET_GEN)awk -f generate-cmdlist.awk command-list.txt > $@+ && mv $@+ $@ > > SCRIPT_DEFINES = $(SHELL_PATH_SQ):$(DIFF_SQ):$(GIT_VERSION):\ > $(localedir_SQ):$(NO_CURL):$(USE_GETTEXT_SCHEME):$(SANE_TOOL_PATH_SQ):\ > diff --git a/generate-cmdlist.awk b/generate-cmdlist.awk > new file mode 100644 > index 0000000..19b36e5 > --- /dev/null > +++ b/generate-cmdlist.awk > @@ -0,0 +1,39 @@ > +BEGIN { > + print "/* Automatically generated */\n" > + print "struct cmdname_help {" > + print "\tchar name[16];" > + print "\tchar help[80];" > + print "\tunsigned char group;" > + print "};\n" > + print "static char *common_cmd_groups[] = {" > +} > +/^#/ || /^[ ]*$/ { next } > +state == 2 { > + for (i = 2; i <= NF; i++) > + if (grp[$i]) { > + f = "Documentation/"$1".txt" > + while (getline s <f > 0) > + if (match(s, $1" - ")) { > + t = substr(s, length($1" - ") + 1) > + break > + } > + close(f) > + printf "\t{\"%s\", N_(\"%s\"), %s},\n", > + substr($1, length("git-") + 1), t, grp[$i] - 1 > + break > + } > +} > +/\[commands\]/ { > + print "};\n\nstatic struct cmdname_help common_cmds[] = {" > + state = 2 > +} > +state == 1 { > + grp[$1] = ++n > + sub($1"[ ][ ]*", "") > + printf "\tN_(\"%s\"),\n", $0 > + next > +} > +/\[common\]/ { > + state = 1 > +} > +END { print "};" } > diff --git a/generate-cmdlist.sh b/generate-cmdlist.sh > deleted file mode 100755 > index 9a4c9b9..0000000 > --- a/generate-cmdlist.sh > +++ /dev/null > @@ -1,23 +0,0 @@ > -#!/bin/sh > - > -echo "/* Automatically generated by $0 */ > -struct cmdname_help { > - char name[16]; > - char help[80]; > -}; > - > -static struct cmdname_help common_cmds[] = {" > - > -sed -n -e 's/^git-\([^ ]*\)[ ].* common.*/\1/p' command-list.txt | > -sort | > -while read cmd > -do > - sed -n ' > - /^NAME/,/git-'"$cmd"'/H > - ${ > - x > - s/.*git-'"$cmd"' - \(.*\)/ {"'"$cmd"'", N_("\1")},/ > - p > - }' "Documentation/git-$cmd.txt" > -done > -echo "};" > Wow. Thanks very much. It has been added in the new version of the patch, including the removal of the 'next' line. ^ permalink raw reply [flat|nested] 38+ messages in thread
* [PATCH 3/3] git help: group common commands by theme 2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara 2015-05-04 20:28 ` [PATCH 1/3] command-list.txt: " Sébastien Guimmara 2015-05-04 20:28 ` [PATCH 2/3] generate-cmdlist.sh: parse common group commands Sébastien Guimmara @ 2015-05-04 20:28 ` Sébastien Guimmara 2015-05-06 3:16 ` Eric Sunshine 2015-05-06 3:08 ` [PATCH 0/3] " Eric Sunshine ` (3 subsequent siblings) 6 siblings, 1 reply; 38+ messages in thread From: Sébastien Guimmara @ 2015-05-04 20:28 UTC (permalink / raw) To: git; +Cc: Sébastien Guimmara, gitster, sunshine 'git help' shows common commands in alphabetical order: The most commonly used git commands are: add Add file contents to the index bisect Find by binary search the change that introduced a bug branch List, create, or delete branches checkout Checkout a branch or paths to the working tree clone Clone a repository into a new directory commit Record changes to the repository [...] without any indication of how commands relate to high-level concepts or each other. Revise the output to group commands by concept, like this: 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 * working on the current change: add Add file contents to the index reset Reset current HEAD to the specified state [...] Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com> --- help.c | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/help.c b/help.c index 2072a87..c8b0bb6 100644 --- a/help.c +++ b/help.c @@ -218,18 +218,44 @@ void list_commands(unsigned int colopts, } } +int cmd_group_cmp(const void *elem1, const void *elem2) +{ + int group1, group2; + + group1 = ((struct cmdname_help *) elem1)->group; + group2 = ((struct cmdname_help *) elem2)->group; + + if (group1 == group2) + return 0; + if (group1 > group2) + return 1; + else + return -1; +} + void list_common_cmds_help(void) { int i, longest = 0; + unsigned char current_grp = -1; for (i = 0; i < ARRAY_SIZE(common_cmds); i++) { if (longest < strlen(common_cmds[i].name)) longest = strlen(common_cmds[i].name); } + qsort(common_cmds, ARRAY_SIZE(common_cmds), + sizeof(common_cmds[0]), cmd_group_cmp); + puts(_("The most commonly used git commands are:")); + for (i = 0; i < ARRAY_SIZE(common_cmds); i++) { - printf(" %s ", common_cmds[i].name); + if (common_cmds[i].group != current_grp) { + printf("\n * %s:\n", _(common_cmd_groups[common_cmds[i].group])); + } + + current_grp = common_cmds[i].group; + + printf(" %s ", common_cmds[i].name); mput_char(' ', longest - strlen(common_cmds[i].name)); puts(_(common_cmds[i].help)); } -- 2.4.0 ^ permalink raw reply related [flat|nested] 38+ messages in thread
* Re: [PATCH 3/3] git help: group common commands by theme 2015-05-04 20:28 ` [PATCH 3/3] git help: group common commands by theme Sébastien Guimmara @ 2015-05-06 3:16 ` Eric Sunshine 2015-05-06 20:31 ` Sébastien Guimmara 2015-05-08 21:08 ` Sébastien Guimmara 0 siblings, 2 replies; 38+ messages in thread From: Eric Sunshine @ 2015-05-06 3:16 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara <sebastien.guimmara@gmail.com> wrote: > 'git help' shows common commands in alphabetical order: > > The most commonly used git commands are: > add Add file contents to the index > bisect Find by binary search the change that introduced a bug > branch List, create, or delete branches > checkout Checkout a branch or paths to the working tree > clone Clone a repository into a new directory > commit Record changes to the repository > [...] > > without any indication of how commands relate to high-level > concepts or each other. Revise the output to group commands by > concept, like this: > > 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 > > * working on the current change: > add Add file contents to the index > reset Reset current HEAD to the specified state > [...] This looks better. A couple minor style nits and a question below... > --- > diff --git a/help.c b/help.c > index 2072a87..c8b0bb6 100644 > --- a/help.c > +++ b/help.c > @@ -218,18 +218,44 @@ void list_commands(unsigned int colopts, > } > } > > +int cmd_group_cmp(const void *elem1, const void *elem2) > +{ > + int group1, group2; > + > + group1 = ((struct cmdname_help *) elem1)->group; > + group2 = ((struct cmdname_help *) elem2)->group; Style: Drop space after the cast: (type *)var > + > + if (group1 == group2) > + return 0; > + if (group1 > group2) > + return 1; > + else > + return -1; Do you also want to sort the commands alphabetically within group? That is, something like this? struct cmdname_help *e1 = elem1; struct cmdname_help *e2 = elem2; if (e1->group < e2->group) return -1; if (e1->group > e2->group) return 1; return strcmp(e1->name, e2->name); > +} > + > void list_common_cmds_help(void) > { > int i, longest = 0; > + unsigned char current_grp = -1; > > for (i = 0; i < ARRAY_SIZE(common_cmds); i++) { > if (longest < strlen(common_cmds[i].name)) > longest = strlen(common_cmds[i].name); > } > > + qsort(common_cmds, ARRAY_SIZE(common_cmds), > + sizeof(common_cmds[0]), cmd_group_cmp); > + > puts(_("The most commonly used git commands are:")); > + > for (i = 0; i < ARRAY_SIZE(common_cmds); i++) { > - printf(" %s ", common_cmds[i].name); > + if (common_cmds[i].group != current_grp) { > + printf("\n * %s:\n", _(common_cmd_groups[common_cmds[i].group])); > + } Style: Drop unnecessary braces. > + current_grp = common_cmds[i].group; Alternately, move this assignment inside the braces. > + printf(" %s ", common_cmds[i].name); > mput_char(' ', longest - strlen(common_cmds[i].name)); > puts(_(common_cmds[i].help)); > } > -- > 2.4.0 ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 3/3] git help: group common commands by theme 2015-05-06 3:16 ` Eric Sunshine @ 2015-05-06 20:31 ` Sébastien Guimmara 2015-05-08 21:08 ` Sébastien Guimmara 1 sibling, 0 replies; 38+ messages in thread From: Sébastien Guimmara @ 2015-05-06 20:31 UTC (permalink / raw) To: Eric Sunshine; +Cc: Git List, Junio C Hamano, Sébastien Guimmara On 05/06/2015 05:16 AM, Eric Sunshine wrote: > On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara > <sebastien.guimmara@gmail.com> wrote: >> 'git help' shows common commands in alphabetical order: >> >> The most commonly used git commands are: >> add Add file contents to the index >> bisect Find by binary search the change that introduced a bug >> branch List, create, or delete branches >> checkout Checkout a branch or paths to the working tree >> clone Clone a repository into a new directory >> commit Record changes to the repository >> [...] >> >> without any indication of how commands relate to high-level >> concepts or each other. Revise the output to group commands by >> concept, like this: >> >> 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 >> >> * working on the current change: >> add Add file contents to the index >> reset Reset current HEAD to the specified state >> [...] > > This looks better. A couple minor style nits and a question below... > >> --- >> diff --git a/help.c b/help.c >> index 2072a87..c8b0bb6 100644 >> --- a/help.c >> +++ b/help.c >> @@ -218,18 +218,44 @@ void list_commands(unsigned int colopts, >> } >> } >> >> +int cmd_group_cmp(const void *elem1, const void *elem2) >> +{ >> + int group1, group2; >> + >> + group1 = ((struct cmdname_help *) elem1)->group; >> + group2 = ((struct cmdname_help *) elem2)->group; > > Style: Drop space after the cast: (type *)var > >> + >> + if (group1 == group2) >> + return 0; >> + if (group1 > group2) >> + return 1; >> + else >> + return -1; > > Do you also want to sort the commands alphabetically within group? > That is, something like this? > > struct cmdname_help *e1 = elem1; > struct cmdname_help *e2 = elem2; > > if (e1->group < e2->group) > return -1; > if (e1->group > e2->group) > return 1; > return strcmp(e1->name, e2->name); > Hmmm yes. Good idea. >> +} >> + >> void list_common_cmds_help(void) >> { >> int i, longest = 0; >> + unsigned char current_grp = -1; >> >> for (i = 0; i < ARRAY_SIZE(common_cmds); i++) { >> if (longest < strlen(common_cmds[i].name)) >> longest = strlen(common_cmds[i].name); >> } >> >> + qsort(common_cmds, ARRAY_SIZE(common_cmds), >> + sizeof(common_cmds[0]), cmd_group_cmp); >> + >> puts(_("The most commonly used git commands are:")); >> + >> for (i = 0; i < ARRAY_SIZE(common_cmds); i++) { >> - printf(" %s ", common_cmds[i].name); >> + if (common_cmds[i].group != current_grp) { >> + printf("\n * %s:\n", _(common_cmd_groups[common_cmds[i].group])); >> + } > > Style: Drop unnecessary braces. Understood. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 3/3] git help: group common commands by theme 2015-05-06 3:16 ` Eric Sunshine 2015-05-06 20:31 ` Sébastien Guimmara @ 2015-05-08 21:08 ` Sébastien Guimmara 2015-05-08 21:17 ` Stefan Beller 1 sibling, 1 reply; 38+ messages in thread From: Sébastien Guimmara @ 2015-05-08 21:08 UTC (permalink / raw) To: Eric Sunshine; +Cc: Git List On 05/06/2015 05:16 AM, Eric Sunshine wrote: > On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara >> + >> + if (group1 == group2) >> + return 0; >> + if (group1 > group2) >> + return 1; >> + else >> + return -1; > > Do you also want to sort the commands alphabetically within group? > That is, something like this? > > struct cmdname_help *e1 = elem1; > struct cmdname_help *e2 = elem2; > > if (e1->group < e2->group) > return -1; > if (e1->group > e2->group) > return 1; > return strcmp(e1->name, e2->name); > >> +} Your version raises: help.c: In function ‘cmd_group_cmp’: help.c:223:28: warning: initialization discards ‘const’ qualifier from pointer target type [enabled by default] struct cmdname_help *e1 = elem1; ^ help.c:224:28: warning: initialization discards ‘const’ qualifier from pointer target type [enabled by default] struct cmdname_help *e2 = elem2; ^ With the cast: struct cmdname_help *e1 = (struct cmdname_help*)elem1; It compiles without a warning (gcc (Ubuntu 4.8.2-19ubuntu1) 4.8.2) >> + >> void list_common_cmds_help(void) >> { >> int i, longest = 0; >> + unsigned char current_grp = -1; >> >> for (i = 0; i < ARRAY_SIZE(common_cmds); i++) { >> if (longest < strlen(common_cmds[i].name)) >> longest = strlen(common_cmds[i].name); >> } >> >> + qsort(common_cmds, ARRAY_SIZE(common_cmds), >> + sizeof(common_cmds[0]), cmd_group_cmp); >> + >> puts(_("The most commonly used git commands are:")); >> + >> for (i = 0; i < ARRAY_SIZE(common_cmds); i++) { >> - printf(" %s ", common_cmds[i].name); >> + if (common_cmds[i].group != current_grp) { >> + printf("\n * %s:\n", _(common_cmd_groups[common_cmds[i].group])); >> + } > > Style: Drop unnecessary braces. > >> + current_grp = common_cmds[i].group; > > Alternately, move this assignment inside the braces. > >> + printf(" %s ", common_cmds[i].name); >> mput_char(' ', longest - strlen(common_cmds[i].name)); >> puts(_(common_cmds[i].help)); >> } >> -- >> 2.4.0 > ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 3/3] git help: group common commands by theme 2015-05-08 21:08 ` Sébastien Guimmara @ 2015-05-08 21:17 ` Stefan Beller 2015-05-08 21:19 ` Eric Sunshine 2015-05-08 21:20 ` Sébastien Guimmara 0 siblings, 2 replies; 38+ messages in thread From: Stefan Beller @ 2015-05-08 21:17 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: Eric Sunshine, Git List On Fri, May 8, 2015 at 2:08 PM, Sébastien Guimmara <sebastien.guimmara@gmail.com> wrote: > On 05/06/2015 05:16 AM, Eric Sunshine wrote: >> >> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara >>> >>> + >>> + if (group1 == group2) >>> + return 0; >>> + if (group1 > group2) >>> + return 1; >>> + else >>> + return -1; >> >> >> Do you also want to sort the commands alphabetically within group? >> That is, something like this? >> >> struct cmdname_help *e1 = elem1; >> struct cmdname_help *e2 = elem2; >> >> if (e1->group < e2->group) >> return -1; >> if (e1->group > e2->group) >> return 1; >> return strcmp(e1->name, e2->name); >> >>> +} > > > Your version raises: > > help.c: In function ‘cmd_group_cmp’: > help.c:223:28: warning: initialization discards ‘const’ qualifier from > pointer target type [enabled by default] > struct cmdname_help *e1 = elem1; > ^ > help.c:224:28: warning: initialization discards ‘const’ qualifier from > pointer target type [enabled by default] > struct cmdname_help *e2 = elem2; > ^ > > With the cast: > > struct cmdname_help *e1 = (struct cmdname_help*)elem1; > > It compiles without a warning (gcc (Ubuntu 4.8.2-19ubuntu1) 4.8.2) > > I'd rather change the type of struct cmdname_help to be const, such that it reads: const struct cmdname_help *e1 = elem1; const struct cmdname_help *e2 = elem2; if (e1->group < e2->group) return -1; if (e1->group > e2->group) return 1; return strcmp(e1->name, e2->name); instead of casting if possible. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 3/3] git help: group common commands by theme 2015-05-08 21:17 ` Stefan Beller @ 2015-05-08 21:19 ` Eric Sunshine 2015-05-08 21:20 ` Sébastien Guimmara 1 sibling, 0 replies; 38+ messages in thread From: Eric Sunshine @ 2015-05-08 21:19 UTC (permalink / raw) To: Stefan Beller; +Cc: Sébastien Guimmara, Git List On Fri, May 8, 2015 at 5:17 PM, Stefan Beller <sbeller@google.com> wrote: > On Fri, May 8, 2015 at 2:08 PM, Sébastien Guimmara > <sebastien.guimmara@gmail.com> wrote: >> On 05/06/2015 05:16 AM, Eric Sunshine wrote: >>> Do you also want to sort the commands alphabetically within group? >>> That is, something like this? >>> >>> struct cmdname_help *e1 = elem1; >>> struct cmdname_help *e2 = elem2; >>> >>> if (e1->group < e2->group) >>> return -1; >>> if (e1->group > e2->group) >>> return 1; >>> return strcmp(e1->name, e2->name); >>> >>>> +} >> >> Your version raises: >> >> help.c:223:28: warning: initialization discards ‘const’ qualifier from >> pointer target type [enabled by default] >> struct cmdname_help *e1 = elem1; >> ^ >> With the cast: >> struct cmdname_help *e1 = (struct cmdname_help*)elem1; >> It compiles without a warning (gcc (Ubuntu 4.8.2-19ubuntu1) 4.8.2) > > I'd rather change the type of struct cmdname_help to be const, such > that it reads: > > const struct cmdname_help *e1 = elem1; > const struct cmdname_help *e2 = elem2; > > if (e1->group < e2->group) > return -1; > if (e1->group > e2->group) > return 1; > return strcmp(e1->name, e2->name); > > instead of casting if possible. Right. That was just a quickly typed example in the email. The "real" code should use a 'const' pointer. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 3/3] git help: group common commands by theme 2015-05-08 21:17 ` Stefan Beller 2015-05-08 21:19 ` Eric Sunshine @ 2015-05-08 21:20 ` Sébastien Guimmara 1 sibling, 0 replies; 38+ messages in thread From: Sébastien Guimmara @ 2015-05-08 21:20 UTC (permalink / raw) To: Stefan Beller, Git Users On 05/08/2015 11:17 PM, Stefan Beller wrote: > On Fri, May 8, 2015 at 2:08 PM, Sébastien Guimmara > <sebastien.guimmara@gmail.com> wrote: >> On 05/06/2015 05:16 AM, Eric Sunshine wrote: >>> >>> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara >>>> >>>> + >>>> + if (group1 == group2) >>>> + return 0; >>>> + if (group1 > group2) >>>> + return 1; >>>> + else >>>> + return -1; >>> >>> >>> Do you also want to sort the commands alphabetically within group? >>> That is, something like this? >>> >>> struct cmdname_help *e1 = elem1; >>> struct cmdname_help *e2 = elem2; >>> >>> if (e1->group < e2->group) >>> return -1; >>> if (e1->group > e2->group) >>> return 1; >>> return strcmp(e1->name, e2->name); >>> >>>> +} >> >> >> Your version raises: >> >> help.c: In function ‘cmd_group_cmp’: >> help.c:223:28: warning: initialization discards ‘const’ qualifier from >> pointer target type [enabled by default] >> struct cmdname_help *e1 = elem1; >> ^ >> help.c:224:28: warning: initialization discards ‘const’ qualifier from >> pointer target type [enabled by default] >> struct cmdname_help *e2 = elem2; >> ^ >> >> With the cast: >> >> struct cmdname_help *e1 = (struct cmdname_help*)elem1; >> >> It compiles without a warning (gcc (Ubuntu 4.8.2-19ubuntu1) 4.8.2) >> >> > > I'd rather change the type of struct cmdname_help to be const, such > that it reads: > > const struct cmdname_help *e1 = elem1; > const struct cmdname_help *e2 = elem2; > > if (e1->group < e2->group) > return -1; > if (e1->group > e2->group) > return 1; > return strcmp(e1->name, e2->name); > > instead of casting if possible. > yes, much better, thanks. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara ` (2 preceding siblings ...) 2015-05-04 20:28 ` [PATCH 3/3] git help: group common commands by theme Sébastien Guimmara @ 2015-05-06 3:08 ` Eric Sunshine 2015-05-06 20:26 ` Sébastien Guimmara 2015-05-06 3:41 ` Junio C Hamano ` (2 subsequent siblings) 6 siblings, 1 reply; 38+ messages in thread From: Eric Sunshine @ 2015-05-06 3:08 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara <sebastien.guimmara@gmail.com> 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 > > - Add a [commands] header on top of the known command list, and > group names as a third column. > > [commands] > git-add mainporcelain common-worktree > git-am mainporcelain > git-annotate ancillaryinterrogators > git-apply plumbingmanipulators > git-archimport foreignscminterface > git-archive mainporcelain > git-bisect mainporcelain > git-blame ancillaryinterrogators > git-branch mainporcelain common-history Thanks, this version is looking better. I, personally, still find the redundant "command-" prefix ugly and would just as soon see it go away. I'll make some suggestions about that when reviewing patch 2/3. More below. > 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 > > * 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 > > * 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 > [...] > > I removed from the list of common commands: rebase, rm, mv, bisect > because [1] they are not really common to an unfamiliar user, [2] to > save vertical space occupied by group headers. Please perform the removals in a separate (preparatory) patch. Not only is it difficult to spot the removals mixed in with the primary changes of 1/3, but they are not even mentioned in the commit message of that patch. More generally, the removals are a logically distinct change from assigning groupings to the common commands, thus deserve their own patch. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-06 3:08 ` [PATCH 0/3] " Eric Sunshine @ 2015-05-06 20:26 ` Sébastien Guimmara 2015-05-06 20:49 ` Eric Sunshine 0 siblings, 1 reply; 38+ messages in thread From: Sébastien Guimmara @ 2015-05-06 20:26 UTC (permalink / raw) To: Eric Sunshine; +Cc: Git List, Junio C Hamano On 05/06/2015 05:08 AM, Eric Sunshine wrote: > On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara > <sebastien.guimmara@gmail.com> 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 >> >> - Add a [commands] header on top of the known command list, and >> group names as a third column. >> >> [commands] >> git-add mainporcelain common-worktree >> git-am mainporcelain >> git-annotate ancillaryinterrogators >> git-apply plumbingmanipulators >> git-archimport foreignscminterface >> git-archive mainporcelain >> git-bisect mainporcelain >> git-blame ancillaryinterrogators >> git-branch mainporcelain common-history > > Thanks, this version is looking better. I, personally, still find the > redundant "command-" prefix ugly and would just as soon see it go > away. I'll make some suggestions about that when reviewing patch 2/3. Indeed, I'm a bit annoyed by this prefix. We could do two things: - either drop the [deprecated] options, since it's never used. - or keep it, but make it exclusive with [common]. It makes sense after all that if a command is deprecated, we don't want to consider it common anymore. In both cases, we end up with only three columns, the third being optional. The common- prefix can then be removed in favor of the group ID alone. >> I removed from the list of common commands: rebase, rm, mv, bisect >> because [1] they are not really common to an unfamiliar user, [2] to >> save vertical space occupied by group headers. > > Please perform the removals in a separate (preparatory) patch. Not > only is it difficult to spot the removals mixed in with the primary > changes of 1/3, but they are not even mentioned in the commit message > of that patch. More generally, the removals are a logically distinct > change from assigning groupings to the common commands, thus deserve > their own patch. > Thanks. I will separate both patches. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-06 20:26 ` Sébastien Guimmara @ 2015-05-06 20:49 ` Eric Sunshine 0 siblings, 0 replies; 38+ messages in thread From: Eric Sunshine @ 2015-05-06 20:49 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: Git List, Junio C Hamano On Wed, May 6, 2015 at 4:26 PM, Sébastien Guimmara <sebastien.guimmara@gmail.com> wrote: > On 05/06/2015 05:08 AM, Eric Sunshine wrote: >> On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara >> <sebastien.guimmara@gmail.com> wrote: >>> - Add a [groups] block containing names and description for groups: >>> >>> [groups] >>> init starting a working area >>> >>> - Add a [commands] header on top of the known command list, and >>> group names as a third column. >>> >>> [commands] >>> git-add mainporcelain common-worktree >> >> Thanks, this version is looking better. I, personally, still find the >> redundant "command-" prefix ugly and would just as soon see it go >> away. I'll make some suggestions about that when reviewing patch 2/3. > > Indeed, I'm a bit annoyed by this prefix. We could do two things: > - either drop the [deprecated] options, since it's never used. > - or keep it, but make it exclusive with [common]. It makes sense after > all that if a command is deprecated, we don't want to consider it > common anymore. > > In both cases, we end up with only three columns, the third being > optional. > > The common- prefix can then be removed in favor of the group ID alone. Sorry for not yet reviewing patch 2/3. I'm trying to find time to review it and make the promised suggestions, however, Real Life keeps getting in the way. If 'deprecated' has never been used and if it is not likely to be used in the future, then dropping that column may indeed be an easy way forward toward the goal of eliminating the "common-" prefix. A possible shortcoming of this columnar approach, however, is that if someone someday comes up with some new type of attribute to assign in a new column, then you still end up in the same boat where not all entries use all columns, and you have difficulty figuring out to which column an attribute belongs. Instead, as mentioned originally, I had envisioned a solution in which any command tagged with an attribute mentioned in [groups] would be considered common, without having to resort to a prefix or fixed columns. This should be more flexible in the long run, but may be overkill for present day. I think that awk should be able to handle this easily, but haven't had the time to actually sit down and flesh it out (which I wanted to do while reviewing 2/3). And, any solution is likely going to have to take into account the two Makefiles Junio mentioned. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara ` (3 preceding siblings ...) 2015-05-06 3:08 ` [PATCH 0/3] " Eric Sunshine @ 2015-05-06 3:41 ` Junio C Hamano 2015-05-08 18:00 ` Sébastien Guimmara 2015-05-06 7:59 ` Matthieu Moy 2015-05-07 9:31 ` Emma Jane Hogbin Westby 6 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2015-05-06 3:41 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: git, sunshine Sébastien Guimmara <sebastien.guimmara@gmail.com> writes: > command-list.txt | 64 +++++++++++++++++++++++++++++++---------------------- > generate-cmdlist.sh | 43 +++++++++++++++++++++++++---------- > help.c | 28 ++++++++++++++++++++++- I did not apply any of these patches to my tree, but $ git grep command-list.txt shows that Documentation/Makefile and Makefile reads from command-list.txt to do their own useful tasks. A patch series that does not touch either of them makes me suspect that it may be breaking a lot of things. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-06 3:41 ` Junio C Hamano @ 2015-05-08 18:00 ` Sébastien Guimmara 2015-05-08 18:53 ` Junio C Hamano 0 siblings, 1 reply; 38+ messages in thread From: Sébastien Guimmara @ 2015-05-08 18:00 UTC (permalink / raw) To: Junio C Hamano, Git Users Hi Junio, A preliminary question to prepare the next round (v5) of this patch: All versions of these patches were based upon the tip of 'master' 2.4.0 (3d4a3ff). Should I rebase subsequent patches on top of 'next' ? Sébastien ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-08 18:00 ` Sébastien Guimmara @ 2015-05-08 18:53 ` Junio C Hamano 0 siblings, 0 replies; 38+ messages in thread From: Junio C Hamano @ 2015-05-08 18:53 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: Git Users Sébastien Guimmara <sebastien.guimmara@gmail.com> writes: > A preliminary question to prepare the next round (v5) of this patch: > > All versions of these patches were based upon the tip of 'master' 2.4.0 > (3d4a3ff). > > Should I rebase subsequent patches on top of 'next' ? I think doing it on 2.4.0 is fine. In general, you shouldn't base anything on 'next', unless you are using some new features that are still cooking in 'next' on their own topic branches. And even if that were the case, I would prefer a series that introduces a new feature to wait for those other topic branches it wants to use to graduate to 'master'. Alternatively, you can identify these still-in-flight topics that you absolutely need to depend on, merge them to 'master' yourself, _and_ build your patches on top, but please make it clear that you did that when sending the patches in if you take this route. Your patches would become hostage of these other topics and cannot graduate to 'master' before they do, so keep that in mind if you do so. Whatever you do, you would still need to make sure that the result of applying your patches merges cleanly to 'next' and works well. Needless to say, a fix is preferrable to be based on 'maint' (or even older maintenance tracks when it is feasible), but that does not concern this "update help output" topic. Thanks. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara ` (4 preceding siblings ...) 2015-05-06 3:41 ` Junio C Hamano @ 2015-05-06 7:59 ` Matthieu Moy 2015-05-06 17:42 ` Junio C Hamano 2015-05-07 9:31 ` Emma Jane Hogbin Westby 6 siblings, 1 reply; 38+ messages in thread From: Matthieu Moy @ 2015-05-06 7:59 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: git, gitster, sunshine Sébastien Guimmara <sebastien.guimmara@gmail.com> writes: > * examining the history and state: > log Show commit logs > status Show the working tree status > > * 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 I would have put "diff" next to "status" in the "examining the history and state" section. It's neither growing, marking nor tweaking the history. > I removed from the list of common commands: rebase, rm, mv, bisect > because [1] they are not really common to an unfamiliar user, I tend to agree for rebase and bisect (even though showing them to beginners may give them a hint on why Git can be good for them). But removing rm and mv seems weird. It seems to me that the obvious question of someone who just learnt "add" would be "and how do I do the opposite?". -- Matthieu Moy http://www-verimag.imag.fr/~moy/ ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-06 7:59 ` Matthieu Moy @ 2015-05-06 17:42 ` Junio C Hamano 2015-05-07 8:42 ` Matthieu Moy 0 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2015-05-06 17:42 UTC (permalink / raw) To: Matthieu Moy; +Cc: Sébastien Guimmara, git, sunshine Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes: > Sébastien Guimmara <sebastien.guimmara@gmail.com> writes: > >> * examining the history and state: >> log Show commit logs >> status Show the working tree status >> >> * 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 > > I would have put "diff" next to "status" in the "examining the history > and state" section. It's neither growing, marking nor tweaking the > history. I am somewhat torn on this. Your suggestion is about "what does this command do?" Which is a perfectly acceptable way to categorize commands once you nailed your workflow down. There is another school of thought to organize them according to "in which phase in your development cycle do you use this command?", i.e. more workflow oriented categorization. From this point of view, "diff" and "status" are important tools you use while "growing your own history". > But removing rm and mv seems weird. It seems to me that the obvious > question of someone who just learnt "add" would be "and how do I do the > opposite?". And the answer may confuse that someone even further (it is not necessarily "rm", but is often "reset"). As a list of simple command set to help the dip-your-toes-in-water process, a new user may be better off starting with "add", "add ." and "commit -a", and learn from the last part of "git add --help" that there are "rm" and "mv" (both of which happen a lot less often than "add"). ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-06 17:42 ` Junio C Hamano @ 2015-05-07 8:42 ` Matthieu Moy 2015-05-07 18:44 ` Junio C Hamano 0 siblings, 1 reply; 38+ messages in thread From: Matthieu Moy @ 2015-05-07 8:42 UTC (permalink / raw) To: Junio C Hamano; +Cc: Sébastien Guimmara, git, sunshine Junio C Hamano <gitster@pobox.com> writes: > And the answer may confuse that someone even further (it is not > necessarily "rm", but is often "reset"). As a list of simple > command set to help the dip-your-toes-in-water process, a new user > may be better off starting with "add", "add ." and "commit -a", and > learn from the last part of "git add --help" that there are "rm" and > "mv" (both of which happen a lot less often than "add"). If one wonders how to remove a file from Git, expecting that user to look at the doc for "git add" to find out seems really backwards to me. -- Matthieu Moy http://www-verimag.imag.fr/~moy/ ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-07 8:42 ` Matthieu Moy @ 2015-05-07 18:44 ` Junio C Hamano 2015-05-08 8:18 ` Matthieu Moy 0 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2015-05-07 18:44 UTC (permalink / raw) To: Matthieu Moy; +Cc: Sébastien Guimmara, git, sunshine Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes: > Junio C Hamano <gitster@pobox.com> writes: > >> And the answer may confuse that someone even further (it is not >> necessarily "rm", but is often "reset"). As a list of simple >> command set to help the dip-your-toes-in-water process, a new user >> may be better off starting with "add", "add ." and "commit -a", and >> learn from the last part of "git add --help" that there are "rm" and >> "mv" (both of which happen a lot less often than "add"). > > If one wonders how to remove a file from Git, expecting that user to > look at the doc for "git add" to find out seems really backwards to me. Yeah, but you are moving the goalpost. What you are reponding to is my reaction to your earlier "the obvious question of someone who just learnt 'add' would be 'and how do I do the _opposite_?'". And I would expect such a person to look at 'add' to find 'SEE ALSO' section. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-07 18:44 ` Junio C Hamano @ 2015-05-08 8:18 ` Matthieu Moy 2015-05-08 16:19 ` Junio C Hamano 0 siblings, 1 reply; 38+ messages in thread From: Matthieu Moy @ 2015-05-08 8:18 UTC (permalink / raw) To: Junio C Hamano; +Cc: Sébastien Guimmara, git, sunshine Junio C Hamano <gitster@pobox.com> writes: > Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes: > >> Junio C Hamano <gitster@pobox.com> writes: >> >>> And the answer may confuse that someone even further (it is not >>> necessarily "rm", but is often "reset"). As a list of simple >>> command set to help the dip-your-toes-in-water process, a new user >>> may be better off starting with "add", "add ." and "commit -a", and >>> learn from the last part of "git add --help" that there are "rm" and >>> "mv" (both of which happen a lot less often than "add"). >> >> If one wonders how to remove a file from Git, expecting that user to >> look at the doc for "git add" to find out seems really backwards to me. > > Yeah, but you are moving the goalpost. Yes, because Git has more than one user and each user may have different ways of thinking. I both find it weird to present "add" without "rm" and to expect users to look at the doc for "add" to find "rm". -- Matthieu Moy http://www-verimag.imag.fr/~moy/ ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-08 8:18 ` Matthieu Moy @ 2015-05-08 16:19 ` Junio C Hamano 0 siblings, 0 replies; 38+ messages in thread From: Junio C Hamano @ 2015-05-08 16:19 UTC (permalink / raw) To: Matthieu Moy; +Cc: Sébastien Guimmara, git, sunshine Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes: > Junio C Hamano <gitster@pobox.com> writes: > >> Yeah, but you are moving the goalpost. > > Yes, because Git has more than one user and each user may have different > ways of thinking. I both find it weird to present "add" without "rm" and > to expect users to look at the doc for "add" to find "rm". I would not expect somebody who wants to find 'rm' to look in 'add', but you were talking about 'I just learnt add. What is the opposite of add?' people. 'remove', 'revert', 'reset', 'unadd'...? Yes, you can try "git help revert", "git help remove", ..., giving all random words you think of in turn, but that is crazy. That is why 'git add' lists related subcommands in SEE ALSO. I do not mind keeping 'rm' with the description of what it does in the list if we had enough vertical space. I think it would hurt to have it in the list without the description of what it does, though, because 'rm' is not opposite of 'add'. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara ` (5 preceding siblings ...) 2015-05-06 7:59 ` Matthieu Moy @ 2015-05-07 9:31 ` Emma Jane Hogbin Westby 2015-05-08 18:21 ` Sébastien Guimmara 6 siblings, 1 reply; 38+ messages in thread From: Emma Jane Hogbin Westby @ 2015-05-07 9:31 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: git, gitster, sunshine Sébastien ! This is fantastic! My apologies for jumping in late. Hopefully I'm not too late. 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) [...] > 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... > * 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. What a wonderful thing to have started, Sébastien ! Thank you. :) ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-07 9:31 ` Emma Jane Hogbin Westby @ 2015-05-08 18:21 ` Sébastien Guimmara 2015-05-08 18:58 ` Junio C Hamano 0 siblings, 1 reply; 38+ messages in thread From: Sébastien Guimmara @ 2015-05-08 18:21 UTC (permalink / raw) To: Emma Jane Hogbin Westby; +Cc: git, Sébastien Guimmara 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 :) ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-08 18:21 ` Sébastien Guimmara @ 2015-05-08 18:58 ` Junio C Hamano 2015-05-08 20:08 ` Sébastien Guimmara 0 siblings, 1 reply; 38+ messages in thread From: Junio C Hamano @ 2015-05-08 18:58 UTC (permalink / raw) To: Sébastien Guimmara; +Cc: Emma Jane Hogbin Westby, git Sébastien Guimmara <sebastien.guimmara@gmail.com> writes: > On 05/07/2015 11:31 AM, Emma Jane Hogbin Westby wrote: > >>> 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. I tend to agree with Emma here; even if your original ordering was not using the workflow as the grouping criterion, that is something that can easily be fixed, I would think. After all, the very original did not categorize and sorted alphabetically, so there is no room for the "we chose to be theme-oriented (I am not sure what it means, though) and a major redesign at this point will confuse users" kind of resistance to come into the picture. At least not yet. Thanks. ^ permalink raw reply [flat|nested] 38+ messages in thread
* Re: [PATCH 0/3] git help: group common commands by theme 2015-05-08 18:58 ` Junio C Hamano @ 2015-05-08 20:08 ` Sébastien Guimmara 0 siblings, 0 replies; 38+ messages in thread From: Sébastien Guimmara @ 2015-05-08 20:08 UTC (permalink / raw) To: Junio C Hamano; +Cc: Emma Jane Hogbin Westby, git On 05/08/2015 08:58 PM, Junio C Hamano wrote: > Sébastien Guimmara <sebastien.guimmara@gmail.com> writes: > >> On 05/07/2015 11:31 AM, Emma Jane Hogbin Westby wrote: >> >>>> 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. > > I tend to agree with Emma here; even if your original ordering was > not using the workflow as the grouping criterion, that is something > that can easily be fixed, I would think. > > After all, the very original did not categorize and sorted > alphabetically, so there is no room for the "we chose to be > theme-oriented (I am not sure what it means, though) and a major > redesign at this point will confuse users" kind of resistance to > come into the picture. At least not yet. > > Thanks. > Exactly. The new version will be workflow-oriented. By "theme-oriented", I mean that the group order does not necessarily follow a "typical workflow" chronological order, even though it was heavily implied. I should emphasize this "workflow" thing in the next patch. ^ permalink raw reply [flat|nested] 38+ messages in thread
end of thread, other threads:[~2015-05-08 21:20 UTC | newest] Thread overview: 38+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2015-05-04 20:28 [PATCH 0/3] git help: group common commands by theme Sébastien Guimmara 2015-05-04 20:28 ` [PATCH 1/3] command-list.txt: " Sébastien Guimmara 2015-05-06 6:57 ` Eric Sunshine 2015-05-06 20:58 ` Sébastien Guimmara 2015-05-07 16:50 ` Eric Sunshine 2015-05-07 19:23 ` Johannes Sixt 2015-05-08 10:11 ` Johannes Schindelin 2015-05-08 12:01 ` Andreas Schwab 2015-05-08 13:02 ` Johannes Schindelin 2015-05-08 18:43 ` Sébastien Guimmara 2015-05-08 19:00 ` Eric Sunshine 2015-05-04 20:28 ` [PATCH 2/3] generate-cmdlist.sh: parse common group commands Sébastien Guimmara 2015-05-08 3:20 ` Eric Sunshine 2015-05-08 3:39 ` Eric Sunshine 2015-05-08 20:55 ` Sébastien Guimmara 2015-05-04 20:28 ` [PATCH 3/3] git help: group common commands by theme Sébastien Guimmara 2015-05-06 3:16 ` Eric Sunshine 2015-05-06 20:31 ` Sébastien Guimmara 2015-05-08 21:08 ` Sébastien Guimmara 2015-05-08 21:17 ` Stefan Beller 2015-05-08 21:19 ` Eric Sunshine 2015-05-08 21:20 ` Sébastien Guimmara 2015-05-06 3:08 ` [PATCH 0/3] " Eric Sunshine 2015-05-06 20:26 ` Sébastien Guimmara 2015-05-06 20:49 ` Eric Sunshine 2015-05-06 3:41 ` Junio C Hamano 2015-05-08 18:00 ` Sébastien Guimmara 2015-05-08 18:53 ` Junio C Hamano 2015-05-06 7:59 ` Matthieu Moy 2015-05-06 17:42 ` Junio C Hamano 2015-05-07 8:42 ` Matthieu Moy 2015-05-07 18:44 ` Junio C Hamano 2015-05-08 8:18 ` Matthieu Moy 2015-05-08 16:19 ` Junio C Hamano 2015-05-07 9:31 ` Emma Jane Hogbin Westby 2015-05-08 18:21 ` Sébastien Guimmara 2015-05-08 18:58 ` Junio C Hamano 2015-05-08 20:08 ` Sébastien Guimmara
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.