Subject: Re: de-alphabetizing the documentation

From: [email-masked]
Date: Fri, 10 Aug 2018 19:30:36 -0700

Hi Jonathan and Git developers,

I poked around today and figured out how to reorder the command
listings in the manual page, they are taken from git/command-list.txt
so I just reorder the lines in that file (after disabling sorting in
git/Documentation/cmd-list.perl).

I haven't reordered the whole list yet. I could only get one computer
friend to send me his subcommand frequencies from his shell history. I
reordered the commands partly based on that, and partly based on their
order of occurrence in the various tutorial man pages.

I'm attaching a preliminary patch (not ready to be applied) just to
make sure this is going to be OK with the maintainer (who is the
maintainer?) before I continue. I made it with "git format-patch".

It seems fairly straightforward, but please let me know if there are
any problems. By the way, the command I used to check that the new
command list contains all the original commands is as follows:

diff =(sort command-list.txt | grep -v '^#') =(git cat-file blob e1c26c1bb7e618f6f372d9a568e7cab75612d2db | grep -v '^#' | sort)

Thanks,

Frederick

On Tue, Jul 24, 2018 at 02:11:46PM -0700, Jonathan Nieder wrote:
> Hi,
> 
> [email-masked] wrote:
> 
> > Next week I should have time to send you a patch with the manual page
> > reordered...
> 
> Yay!
> 
> >               although, unless you have a special 'diff' which can
> > detect when text has been moved from one place to another, I'm
> > guessing it would take you even longer to check the validity of the
> > patch than it would for me to create it.
> 
> Fortunately we have "git diff --color-moved".
> 
> > However, I'm happy to do this or whatever other small projects you
> > would like to delegate as far as improving readability of your
> > documentation. I just need to know what is likely to be accepted.
> 
> Starting with this one seems fine.  Maybe people on list will have
> ideas for followups on top, or maybe you'll have ideas for ways others
> can help you, or both. ;-)
> 
> Thanks again,
> Jonathan
> 
>From 7aabe1060eabee16fac239ce49b8f9749be11adb Mon Sep 17 00:00:00 2001
From: Frederick Eaton <[email-masked]>
Date: Fri, 10 Aug 2018 18:54:28 -0700
Subject: [PATCH] First test of command reordering

---
 Documentation/cmd-list.perl |   2 +-
 command-list.txt            | 107 +++++++++++++++++++++++++-------------------
 2 files changed, 61 insertions(+), 48 deletions(-)

diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 5aa73cfe4..62c32f58d 100755
--- a/Documentation/cmd-list.perl
+++ b/Documentation/cmd-list.perl
@@ -43,7 +43,7 @@ sub format_one {
 }
 
 my %cmds = ();
-for (sort <>) {
+for (<>) {
 	next if /^#/;
 
 	chomp;
diff --git a/command-list.txt b/command-list.txt
index e1c26c1bb..94a15fd42 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -43,35 +43,83 @@
 # specified here, which can only have "guide" attribute and nothing
 # else.
 #
+# August 2018: The list has been reordered for didactic purposes,
+# basically according to approximate usefulness / frequency of use /
+# order of use. This is to make it possible for a beginner to read the
+# manual page "straight through" and see the most important commands
+# first, rather than getting them in alphabetical order. Please
+# consider this when adding new commands.
+#
 ### command list (do not change this line, also do not change alignment)
 # command name                          category [category] [category]
+# From tutorial
+git-help                                ancillaryinterrogators          complete
+git-config                              ancillarymanipulators           complete
+git-clone                               mainporcelain           init
+git-init                                mainporcelain           init
 git-add                                 mainporcelain           worktree
-git-am                                  mainporcelain
+git-commit                              mainporcelain           history
+git-diff                                mainporcelain           history
+git-status                              mainporcelain           info
+git-log                                 mainporcelain           info
+git-branch                              mainporcelain           history
+git-checkout                            mainporcelain           history
+git-merge                               mainporcelain           history
+gitk                                    mainporcelain
+git-pull                                mainporcelain           remote
+git-fetch                               mainporcelain           remote
+# From frequencies
+git-grep                                mainporcelain           info
+git-show                                mainporcelain           info
+git-push                                mainporcelain           remote
+git-submodule                           mainporcelain
+git-reset                               mainporcelain           worktree
+git-cherry-pick                         mainporcelain
+git-tag                                 mainporcelain           history
+git-clean                               mainporcelain
+# From tutorial NEXT STEPS
+git-format-patch                        mainporcelain
+git-bisect                              mainporcelain           info
+gitworkflows                            guide
+giteveryday                             guide
+gitcvs-migration                        guide
+# From tutorial-2 (+ls-remote)
+git-cat-file                            plumbinginterrogators
+git-ls-tree                             plumbinginterrogators
+git-ls-files                            plumbinginterrogators
+git-ls-remote                           plumbinginterrogators
+gitcore-tutorial                        guide
+gitglossary                             guide
+# From gitcore-tutorial
+git-update-index                        plumbingmanipulators
+git-diff-files                          plumbinginterrogators
+git-write-tree                          plumbingmanipulators
+git-read-tree                           plumbingmanipulators
+git-checkout-index                      plumbingmanipulators
+git-show-branch                         ancillaryinterrogators          complete
+git-name-rev                            plumbinginterrogators
+git-merge-index                         plumbingmanipulators
+git-repack                              ancillarymanipulators           complete
+git-prune-packed                        plumbingmanipulators
+git-update-server-info                  synchingrepositories
+git-prune                               ancillarymanipulators
+git-cherry                              ancillaryinterrogators          complete
+# Remaining unsorted (alphabetized) commands
 git-annotate                            ancillaryinterrogators
 git-apply                               plumbingmanipulators            complete
 git-archimport                          foreignscminterface
 git-archive                             mainporcelain
-git-bisect                              mainporcelain           info
 git-blame                               ancillaryinterrogators          complete
-git-branch                              mainporcelain           history
+git-am                                  mainporcelain
 git-bundle                              mainporcelain
-git-cat-file                            plumbinginterrogators
 git-check-attr                          purehelpers
 git-check-ignore                        purehelpers
 git-check-mailmap                       purehelpers
-git-checkout                            mainporcelain           history
-git-checkout-index                      plumbingmanipulators
 git-check-ref-format                    purehelpers
-git-cherry                              ancillaryinterrogators          complete
-git-cherry-pick                         mainporcelain
 git-citool                              mainporcelain
-git-clean                               mainporcelain
-git-clone                               mainporcelain           init
 git-column                              purehelpers
-git-commit                              mainporcelain           history
 git-commit-graph                        plumbingmanipulators
 git-commit-tree                         plumbingmanipulators
-git-config                              ancillarymanipulators           complete
 git-count-objects                       ancillaryinterrogators
 git-credential                          purehelpers
 git-credential-cache                    purehelpers
@@ -81,52 +129,37 @@ git-cvsimport                           foreignscminterface
 git-cvsserver                           foreignscminterface
 git-daemon                              synchingrepositories
 git-describe                            mainporcelain
-git-diff                                mainporcelain           history
-git-diff-files                          plumbinginterrogators
 git-diff-index                          plumbinginterrogators
 git-diff-tree                           plumbinginterrogators
 git-difftool                            ancillaryinterrogators          complete
 git-fast-export                         ancillarymanipulators
 git-fast-import                         ancillarymanipulators
-git-fetch                               mainporcelain           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          complete
 git-gc                                  mainporcelain
 git-get-tar-commit-id                   ancillaryinterrogators
-git-grep                                mainporcelain           info
 git-gui                                 mainporcelain
 git-hash-object                         plumbingmanipulators
-git-help                                ancillaryinterrogators          complete
 git-http-backend                        synchingrepositories
 git-http-fetch                          synchelpers
 git-http-push                           synchelpers
 git-imap-send                           foreignscminterface
 git-index-pack                          plumbingmanipulators
-git-init                                mainporcelain           init
 git-instaweb                            ancillaryinterrogators          complete
 git-interpret-trailers                  purehelpers
-gitk                                    mainporcelain
-git-log                                 mainporcelain           info
-git-ls-files                            plumbinginterrogators
-git-ls-remote                           plumbinginterrogators
-git-ls-tree                             plumbinginterrogators
 git-mailinfo                            purehelpers
 git-mailsplit                           purehelpers
-git-merge                               mainporcelain           history
 git-merge-base                          plumbinginterrogators
 git-merge-file                          plumbingmanipulators
-git-merge-index                         plumbingmanipulators
 git-merge-one-file                      purehelpers
 git-mergetool                           ancillarymanipulators           complete
 git-merge-tree                          ancillaryinterrogators
 git-mktag                               plumbingmanipulators
 git-mktree                              plumbingmanipulators
 git-mv                                  mainporcelain           worktree
-git-name-rev                            plumbinginterrogators
 git-notes                               mainporcelain
 git-p4                                  foreignscminterface
 git-pack-objects                        plumbingmanipulators
@@ -134,21 +167,14 @@ git-pack-redundant                      plumbinginterrogators
 git-pack-refs                           ancillarymanipulators
 git-parse-remote                        synchelpers
 git-patch-id                            purehelpers
-git-prune                               ancillarymanipulators
-git-prune-packed                        plumbingmanipulators
-git-pull                                mainporcelain           remote
-git-push                                mainporcelain           remote
 git-quiltimport                         foreignscminterface
-git-read-tree                           plumbingmanipulators
 git-rebase                              mainporcelain           history
 git-receive-pack                        synchelpers
 git-reflog                              ancillarymanipulators           complete
 git-remote                              ancillarymanipulators           complete
-git-repack                              ancillarymanipulators           complete
 git-replace                             ancillarymanipulators           complete
 git-request-pull                        foreignscminterface             complete
 git-rerere                              ancillaryinterrogators
-git-reset                               mainporcelain           worktree
 git-revert                              mainporcelain
 git-rev-list                            plumbinginterrogators
 git-rev-parse                           ancillaryinterrogators
@@ -157,25 +183,18 @@ git-send-email                          foreignscminterface             complete
 git-send-pack                           synchingrepositories
 git-shell                               synchelpers
 git-shortlog                            mainporcelain
-git-show                                mainporcelain           info
-git-show-branch                         ancillaryinterrogators          complete
 git-show-index                          plumbinginterrogators
 git-show-ref                            plumbinginterrogators
 git-sh-i18n                             purehelpers
 git-sh-setup                            purehelpers
 git-stash                               mainporcelain
 git-stage                                                               complete
-git-status                              mainporcelain           info
 git-stripspace                          purehelpers
-git-submodule                           mainporcelain
 git-svn                                 foreignscminterface
 git-symbolic-ref                        plumbingmanipulators
-git-tag                                 mainporcelain           history
 git-unpack-file                         plumbinginterrogators
 git-unpack-objects                      plumbingmanipulators
-git-update-index                        plumbingmanipulators
 git-update-ref                          plumbingmanipulators
-git-update-server-info                  synchingrepositories
 git-upload-archive                      synchelpers
 git-upload-pack                         synchelpers
 git-var                                 plumbinginterrogators
@@ -185,14 +204,9 @@ git-verify-tag                          ancillaryinterrogators
 gitweb                                  ancillaryinterrogators
 git-whatchanged                         ancillaryinterrogators          complete
 git-worktree                            mainporcelain
-git-write-tree                          plumbingmanipulators
 gitattributes                           guide
 gitcli                                  guide
-gitcore-tutorial                        guide
-gitcvs-migration                        guide
 gitdiffcore                             guide
-giteveryday                             guide
-gitglossary                             guide
 githooks                                guide
 gitignore                               guide
 gitmodules                              guide
@@ -201,4 +215,3 @@ gitrepository-layout                    guide
 gitrevisions                            guide
 gittutorial-2                           guide
 gittutorial                             guide
-gitworkflows                            guide
-- 
2.13.1