From: Junio C Hamano <junkio@cox.net>
To: Nicolas Pitre <nico@cam.org>
Cc: git@vger.kernel.org
Subject: [PATCH] Documentation/git.txt: command re-classification
Date: Thu, 18 Jan 2007 22:32:38 -0800 [thread overview]
Message-ID: <7v1wlrle61.fsf@assigned-by-dhcp.cox.net> (raw)
In-Reply-To: <Pine.LNX.4.64.0701181713200.2577@xanadu.home> (Nicolas Pitre's message of "Thu, 18 Jan 2007 17:25:41 -0500 (EST)")
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 demotes some others.
Signed-off-by: Junio C Hamano <junkio@cox.net>
---
* I unfortunately had to drop your patch on the floor, because
I was cooking a few patches to automate the maintenance of
the command list (which are now in 'master' and the product is
being served at www.kernel.org/pub/software/scm/git/docs/),
which majorly conflicted with your work.
So here is a counterproposal; I moved commands across groups
after looking at what your patch did, but classified some of
them differently.
Documentation/Makefile | 5 ++-
Documentation/cmd-list.perl | 88 ++++++++++++++++++++++---------------------
Documentation/git.txt | 35 ++++++++++++++++-
3 files changed, 83 insertions(+), 45 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 96755ad..19b2505 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) $(MAN7_TXT)
perl ./cmd-list.perl
diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 5680dcb..9443ab3 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}}) {
@@ -60,9 +63,9 @@ git-add mainporcelain
git-am mainporcelain
git-annotate ancillaryinterrogators
git-applymbox mainporcelain
-git-applypatch ancillarymanipulators
+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-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-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 ac22206..ded48b5 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. To put it another way, the
+interface to Plumbing commands 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
-----------------------
--
1.5.0.rc1.g72fe
next prev parent reply other threads:[~2007-01-19 6:32 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2007-01-18 22:25 [PATCH] Documentation: revisit command qualification in git.txt Nicolas Pitre
2007-01-19 6:32 ` Junio C Hamano [this message]
2007-01-19 22:08 ` [PATCH] Documentation/git.txt: command re-classification Nicolas Pitre
2007-01-19 22:18 ` Jakub Narebski
2007-01-19 22:22 ` Junio C Hamano
2007-01-19 22:44 ` Nicolas Pitre
2007-01-19 22:57 ` Jakub Narebski
2007-01-19 22:59 ` J. Bruce Fields
2007-01-19 23:36 ` Junio C Hamano
2007-01-20 1:44 ` Nicolas Pitre
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7v1wlrle61.fsf@assigned-by-dhcp.cox.net \
--to=junkio@cox.net \
--cc=git@vger.kernel.org \
--cc=nico@cam.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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.