From 89bf207758530fd151895680f7236ce626feea9c Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 18 Jan 2007 22:32:38 -0800 Subject: [PATCH] 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 --- Documentation/Makefile | 5 +- Documentation/cmd-list.perl | 94 +++++++++++++++++++------------------ Documentation/git.txt | 35 +++++++++++++- 3 files changed, 86 insertions(+), 48 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 97ea133b4..5314068d3 100644 --- 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-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 diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 5680dcbf9..744db8241 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -45,7 +45,10 @@ for my $cat (qw(ancillaryinterrogators 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}}) { @@ -59,10 +62,10 @@ __DATA__ 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-archimport ancillarymanipulators +git-archimport foreignscminterface git-archive mainporcelain git-bisect mainporcelain git-blame ancillaryinterrogators @@ -70,7 +73,7 @@ git-branch 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 @@ -79,11 +82,11 @@ git-commit mainporcelain 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 @@ -91,34 +94,34 @@ git-diff-stages plumbinginterrogators 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-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-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-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-ls-remote mainporcelain +git-ls-remote 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-one-file ancillarymanipulators +git-merge-one-file purehelpers git-merge-tree ancillaryinterrogators git-mktag plumbingmanipulators git-mktree plumbingmanipulators @@ -126,24 +129,24 @@ git-mv mainporcelain 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-quiltimport ancillarymanipulators +git-quiltimport foreignscminterface git-read-tree plumbingmanipulators git-rebase mainporcelain -git-receive-pack synchingrepositories +git-receive-pack synchelpers 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 @@ -151,34 +154,33 @@ git-rev-list plumbinginterrogators git-rev-parse ancillaryinterrogators git-rm mainporcelain git-runstatus ancillaryinterrogators -git-send-email ancillaryinterrogators +git-send-email foreignscminterface git-send-pack synchingrepositories -git-shell synchingrepositories +git-shell synchelpers git-shortlog mainporcelain git-show mainporcelain -git-show-branch mainporcelain +git-show-branch ancillaryinterrogators 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-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-update-ref ancillarymanipulators +git-update-ref plumbingmanipulators 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-verify-tag mainporcelain -git-whatchanged mainporcelain +git-verify-tag ancillaryinterrogators +git-whatchanged ancillaryinterrogators git-write-tree plumbingmanipulators diff --git a/Documentation/git.txt b/Documentation/git.txt index ac222060e..9761de36b 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -93,6 +93,16 @@ Interrogators: 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) ----------------------------- @@ -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]. -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. + Manipulation commands ~~~~~~~~~~~~~~~~~~~~~ @@ -127,6 +146,20 @@ Synching repositories 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 ----------------------- -- 2.26.2