Documentation/git.txt: command re-classification

This adds two new classes (pure-helpers and "Interacting with
Others") to the command list in the main manual page.  The
latter class is primarily about foreign SCM interface and is
placed before low-level (plumbing) commands.

Also it promotes a handful commands to mainporcelain category
while demoting some others.

Signed-off-by: Junio C Hamano <junkio@cox.net>

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 97ea133b43da0a1f930f6ec6f3d2f6364ec159d5..5314068d32f1e9205ec7b76c9356674a414d773c 100644 (file)
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -76,7 +76,10 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
        cmds-mainporcelain.txt \
        cmds-plumbinginterrogators.txt \
        cmds-plumbingmanipulators.txt \
        cmds-mainporcelain.txt \
        cmds-plumbinginterrogators.txt \
        cmds-plumbingmanipulators.txt \

-       cmds-synchingrepositories.txt
+       cmds-synchingrepositories.txt \
+       cmds-synchelpers.txt \
+       cmds-purehelpers.txt \
+       cmds-foreignscminterface.txt

 
 $(cmds_txt): cmd-list.perl $(MAN1_TXT)
        perl ./cmd-list.perl
 
 $(cmds_txt): cmd-list.perl $(MAN1_TXT)
        perl ./cmd-list.perl

diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 5680dcbf9ab7a9f05a2cf9725942b266fa7586d5..744db82413fbd31f4dd906c2a46702a20953b6c5 100755 (executable)
--- a/Documentation/cmd-list.perl
+++ b/Documentation/cmd-list.perl
@@ -45,7 +45,10 @@ sub format_one {
                mainporcelain
                plumbinginterrogators
                plumbingmanipulators
                mainporcelain
                plumbinginterrogators
                plumbingmanipulators

-               synchingrepositories)) {
+               synchingrepositories
+               foreignscminterface
+               purehelpers
+               synchelpers)) {

        my $out = "cmds-$cat.txt";
        open O, '>', "$out+" or die "Cannot open output file $out+";
        for (@{$cmds{$cat}}) {
        my $out = "cmds-$cat.txt";
        open O, '>', "$out+" or die "Cannot open output file $out+";
        for (@{$cmds{$cat}}) {


@@ -59,10 +62,10 @@ sub format_one {
 git-add                                 mainporcelain
 git-am                                  mainporcelain
 git-annotate                            ancillaryinterrogators
 git-add                                 mainporcelain
 git-am                                  mainporcelain
 git-annotate                            ancillaryinterrogators

-git-applymbox                           mainporcelain
-git-applypatch                          ancillarymanipulators
+git-applymbox                           ancillaryinterrogators
+git-applypatch                          purehelpers

 git-apply                               plumbingmanipulators
 git-apply                               plumbingmanipulators

-git-archimport                          ancillarymanipulators
+git-archimport                          foreignscminterface

 git-archive                             mainporcelain
 git-bisect                              mainporcelain
 git-blame                               ancillaryinterrogators
 git-archive                             mainporcelain
 git-bisect                              mainporcelain
 git-blame                               ancillaryinterrogators


@@ -70,7 +73,7 @@ sub format_one {
 git-cat-file                            plumbinginterrogators
 git-checkout-index                      plumbingmanipulators
 git-checkout                            mainporcelain
 git-cat-file                            plumbinginterrogators
 git-checkout-index                      plumbingmanipulators
 git-checkout                            mainporcelain

-git-check-ref-format                    ancillaryinterrogators
+git-check-ref-format                    purehelpers

 git-cherry                              ancillaryinterrogators
 git-cherry-pick                         mainporcelain
 git-clean                               mainporcelain
 git-cherry                              ancillaryinterrogators
 git-cherry-pick                         mainporcelain
 git-clean                               mainporcelain


@@ -79,11 +82,11 @@ sub format_one {
 git-commit-tree                         plumbingmanipulators
 git-convert-objects                     ancillarymanipulators
 git-count-objects                       ancillaryinterrogators
 git-commit-tree                         plumbingmanipulators
 git-convert-objects                     ancillarymanipulators
 git-count-objects                       ancillaryinterrogators

-git-cvsexportcommit                     ancillarymanipulators
-git-cvsimport                           ancillarymanipulators
-git-cvsserver                           ancillarymanipulators
-git-daemon                              ancillaryinterrogators
-git-describe                            plumbinginterrogators
+git-cvsexportcommit                     foreignscminterface
+git-cvsimport                           foreignscminterface
+git-cvsserver                           foreignscminterface
+git-daemon                              synchingrepositories
+git-describe                            mainporcelain

 git-diff-files                          plumbinginterrogators
 git-diff-index                          plumbinginterrogators
 git-diff                                mainporcelain
 git-diff-files                          plumbinginterrogators
 git-diff-index                          plumbinginterrogators
 git-diff                                mainporcelain


@@ -91,34 +94,34 @@ sub format_one {
 git-diff-tree                           plumbinginterrogators
 git-fetch                               mainporcelain
 git-fetch-pack                          synchingrepositories
 git-diff-tree                           plumbinginterrogators
 git-fetch                               mainporcelain
 git-fetch-pack                          synchingrepositories

-git-fmt-merge-msg                       ancillaryinterrogators
+git-fmt-merge-msg                       purehelpers

 git-for-each-ref                        plumbinginterrogators
 git-format-patch                        mainporcelain
 git-for-each-ref                        plumbinginterrogators
 git-format-patch                        mainporcelain

-git-fsck-objects                        plumbinginterrogators
-git-gc                                  ancillarymanipulators
+git-fsck-objects                        ancillaryinterrogators
+git-gc                                  mainporcelain

 git-get-tar-commit-id                   ancillaryinterrogators
 git-grep                                mainporcelain
 git-hash-object                         plumbingmanipulators
 git-get-tar-commit-id                   ancillaryinterrogators
 git-grep                                mainporcelain
 git-hash-object                         plumbingmanipulators

-git-http-fetch                          synchingrepositories
-git-http-push                           synchingrepositories
-git-imap-send                           ancillaryinterrogators
+git-http-fetch                          synchelpers
+git-http-push                           synchelpers
+git-imap-send                           foreignscminterface

 git-index-pack                          plumbingmanipulators
 git-index-pack                          plumbingmanipulators

-git-init                                plumbingmanipulators
+git-init                                mainporcelain

 git-instaweb                            ancillaryinterrogators
 gitk                                    mainporcelain
 git-local-fetch                         synchingrepositories
 git-log                                 mainporcelain
 git-lost-found                          ancillarymanipulators
 git-ls-files                            plumbinginterrogators
 git-instaweb                            ancillaryinterrogators
 gitk                                    mainporcelain
 git-local-fetch                         synchingrepositories
 git-log                                 mainporcelain
 git-lost-found                          ancillarymanipulators
 git-ls-files                            plumbinginterrogators

-git-ls-remote                           mainporcelain
+git-ls-remote                           plumbinginterrogators

 git-ls-tree                             plumbinginterrogators
 git-ls-tree                             plumbinginterrogators

-git-mailinfo                            ancillaryinterrogators
-git-mailsplit                           ancillaryinterrogators
+git-mailinfo                            purehelpers
+git-mailsplit                           purehelpers

 git-merge-base                          plumbinginterrogators
 git-merge-file                          plumbingmanipulators
 git-merge-index                         plumbingmanipulators
 git-merge                               mainporcelain
 git-merge-base                          plumbinginterrogators
 git-merge-file                          plumbingmanipulators
 git-merge-index                         plumbingmanipulators
 git-merge                               mainporcelain

-git-merge-one-file                      ancillarymanipulators
+git-merge-one-file                      purehelpers

 git-merge-tree                          ancillaryinterrogators
 git-mktag                               plumbingmanipulators
 git-mktree                              plumbingmanipulators
 git-merge-tree                          ancillaryinterrogators
 git-mktag                               plumbingmanipulators
 git-mktree                              plumbingmanipulators


@@ -126,24 +129,24 @@ sub format_one {
 git-name-rev                            plumbinginterrogators
 git-pack-objects                        plumbingmanipulators
 git-pack-redundant                      plumbinginterrogators
 git-name-rev                            plumbinginterrogators
 git-pack-objects                        plumbingmanipulators
 git-pack-redundant                      plumbinginterrogators

-git-pack-refs                           mainporcelain
-git-parse-remote                        ancillaryinterrogators
-git-patch-id                            ancillaryinterrogators
-git-peek-remote                         synchingrepositories
+git-pack-refs                           ancillarymanipulators
+git-parse-remote                        synchelpers
+git-patch-id                            purehelpers
+git-peek-remote                         purehelpers

 git-prune                               ancillarymanipulators
 git-prune-packed                        plumbingmanipulators
 git-pull                                mainporcelain
 git-push                                mainporcelain
 git-prune                               ancillarymanipulators
 git-prune-packed                        plumbingmanipulators
 git-pull                                mainporcelain
 git-push                                mainporcelain

-git-quiltimport                         ancillarymanipulators
+git-quiltimport                         foreignscminterface

 git-read-tree                           plumbingmanipulators
 git-rebase                              mainporcelain
 git-read-tree                           plumbingmanipulators
 git-rebase                              mainporcelain

-git-receive-pack                        synchingrepositories
+git-receive-pack                        synchelpers

 git-reflog                              ancillarymanipulators
 git-relink                              ancillarymanipulators
 git-reflog                              ancillarymanipulators
 git-relink                              ancillarymanipulators

-git-repack                              mainporcelain
-git-repo-config                         plumbingmanipulators
-git-request-pull                        ancillaryinterrogators
-git-rerere                              mainporcelain
+git-repack                              ancillarymanipulators
+git-repo-config                         ancillarymanipulators
+git-request-pull                        foreignscminterface
+git-rerere                              ancillaryinterrogators

 git-reset                               mainporcelain
 git-resolve                             mainporcelain
 git-revert                              mainporcelain
 git-reset                               mainporcelain
 git-resolve                             mainporcelain
 git-revert                              mainporcelain


@@ -151,34 +154,33 @@ sub format_one {
 git-rev-parse                           ancillaryinterrogators
 git-rm                                  mainporcelain
 git-runstatus                           ancillaryinterrogators
 git-rev-parse                           ancillaryinterrogators
 git-rm                                  mainporcelain
 git-runstatus                           ancillaryinterrogators

-git-send-email                          ancillaryinterrogators
+git-send-email                          foreignscminterface

 git-send-pack                           synchingrepositories
 git-send-pack                           synchingrepositories

-git-shell                               synchingrepositories
+git-shell                               synchelpers

 git-shortlog                            mainporcelain
 git-show                                mainporcelain
 git-shortlog                            mainporcelain
 git-show                                mainporcelain

-git-show-branch                         mainporcelain
+git-show-branch                         ancillaryinterrogators

 git-show-index                          plumbinginterrogators
 git-show-ref                            plumbinginterrogators
 git-show-index                          plumbinginterrogators
 git-show-ref                            plumbinginterrogators

-git-sh-setup                            ancillarymanipulators
+git-sh-setup                            purehelpers

 git-ssh-fetch                           synchingrepositories
 git-ssh-upload                          synchingrepositories
 git-status                              mainporcelain
 git-ssh-fetch                           synchingrepositories
 git-ssh-upload                          synchingrepositories
 git-status                              mainporcelain

-git-stripspace                          ancillaryinterrogators
-git-svn                                 ancillarymanipulators
-git-svnimport                           ancillarymanipulators
-git-symbolic-ref                        ancillaryinterrogators
-git-symbolic-ref                        ancillarymanipulators
-git-tag                                 ancillarymanipulators
+git-stripspace                          purehelpers
+git-svn                                 foreignscminterface
+git-svnimport                           foreignscminterface
+git-symbolic-ref                        plumbingmanipulators
+git-tag                                 mainporcelain

 git-tar-tree                            plumbinginterrogators
 git-unpack-file                         plumbinginterrogators
 git-unpack-objects                      plumbingmanipulators
 git-update-index                        plumbingmanipulators
 git-tar-tree                            plumbinginterrogators
 git-unpack-file                         plumbinginterrogators
 git-unpack-objects                      plumbingmanipulators
 git-update-index                        plumbingmanipulators

-git-update-ref                          ancillarymanipulators
+git-update-ref                          plumbingmanipulators

 git-update-server-info                  synchingrepositories
 git-update-server-info                  synchingrepositories

-git-upload-archive                      synchingrepositories
-git-upload-pack                         synchingrepositories
+git-upload-archive                      synchelpers
+git-upload-pack                         synchelpers

 git-var                                 plumbinginterrogators
 git-verify-pack                         plumbinginterrogators
 git-var                                 plumbinginterrogators
 git-verify-pack                         plumbinginterrogators

-git-verify-tag                          mainporcelain
-git-whatchanged                         mainporcelain
+git-verify-tag                          ancillaryinterrogators
+git-whatchanged                         ancillaryinterrogators

 git-write-tree                          plumbingmanipulators
 git-write-tree                          plumbingmanipulators

diff --git a/Documentation/git.txt b/Documentation/git.txt
index ac222060ea08000a17ceed4149a257482ae1e064..9761de36b3cad64bc3bb3b91da7d4fe8656875a6 100644 (file)
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -93,6 +93,16 @@ Interrogators:
 
 include::cmds-ancillaryinterrogators.txt[]
 
 
 include::cmds-ancillaryinterrogators.txt[]
 

+
+Interacting with Others
+~~~~~~~~~~~~~~~~~~~~~~~
+
+These commands are to interact with foreign SCM and with other
+people via patch over e-mail.
+
+include::cmds-foreignscminterface.txt[]
+
+

 Low-level commands (plumbing)
 -----------------------------
 
 Low-level commands (plumbing)
 -----------------------------
 


@@ -102,11 +112,20 @@ development of alternative porcelains.  Developers of such porcelains
 might start by reading about gitlink:git-update-index[1] and
 gitlink:git-read-tree[1].
 
 might start by reading about gitlink:git-update-index[1] and
 gitlink:git-read-tree[1].
 

-We divide the low-level commands into commands that manipulate objects (in
+The interface (input, output, set of options and the semantics)
+to these low-level commands are meant to be a lot more stable
+than Porcelain level commands, because these commands are
+primarily for scripted use.  The interface to Porcelain commands
+on the other hand are subject to change in order to improve the
+end user experience.
+
+The following description divides
+the low-level commands into commands that manipulate objects (in

 the repository, index, and working tree), commands that interrogate and
 compare objects, and commands that move objects and references between
 repositories.
 
 the repository, index, and working tree), commands that interrogate and
 compare objects, and commands that move objects and references between
 repositories.
 

+

 Manipulation commands
 ~~~~~~~~~~~~~~~~~~~~~
 
 Manipulation commands
 ~~~~~~~~~~~~~~~~~~~~~
 


@@ -127,6 +146,20 @@ Synching repositories
 
 include::cmds-synchingrepositories.txt[]
 
 
 include::cmds-synchingrepositories.txt[]
 

+The following are helper programs used by the above; end users
+typically do not use them directly.
+
+include::cmds-synchelpers.txt[]
+
+
+Internal helper commands
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+These are internal helper commands used by other commands; end
+users typically do not use them directly.
+
+include::cmds-purehelpers.txt[]
+

 
 Configuration Mechanism
 -----------------------
 
 Configuration Mechanism
 -----------------------