[PATCH] Documentation: revisit command qualification in git.txt

[PATCH] Documentation: revisit command qualification in git.txt

[Nicolas Pitre]

In particular, the "Main porcelain commands" section should focus on the 
minimum subset of obvious commands an average user is likely to ever 
need.

Commands that are not useful on their own should definitely be in the 
plumbing section.

Signed-off-by: Nicolas Pitre <nico@cam.org>
---
diff --git a/Documentation/git.txt b/Documentation/git.txt
index a0bcef7..db83b69 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -102,9 +102,6 @@ gitlink:git-branch[1]::
 gitlink:git-checkout[1]::
 	Checkout and switch to a branch.
 
-gitlink:git-cherry-pick[1]::
-	Cherry-pick the effect of an existing commit.
-
 gitlink:git-clean[1]::
 	Remove untracked files from the working tree.
 
@@ -123,27 +120,28 @@ gitlink:git-fetch[1]::
 gitlink:git-format-patch[1]::
 	Prepare patches for e-mail submission.
 
+gitlink:git-gc[1]::
+	Cleanup unnecessary files and optimize the local repository.
+
 gitlink:git-grep[1]::
 	Print lines matching a pattern.
 
+gitlink:git-init[1]::
+	Creates an empty git repository, or reinitialize an
+	existing one.
+
 gitlink:gitk[1]::
 	The git repository browser.
 
 gitlink:git-log[1]::
 	Shows commit logs.
 
-gitlink:git-ls-remote[1]::
-	Shows references in a remote or local repository.
-
 gitlink:git-merge[1]::
 	Grand unified merge driver.
 
 gitlink:git-mv[1]::
 	Move or rename a file, a directory, or a symlink.
 
-gitlink:git-pack-refs[1]::
-	Pack heads and tags for efficient repository access.
-
 gitlink:git-pull[1]::
 	Fetch from and merge with a remote repository or a local branch.
 
@@ -153,9 +151,6 @@ gitlink:git-push[1]::
 gitlink:git-rebase[1]::
 	Rebase local commits to the updated upstream head.
 
-gitlink:git-repack[1]::
-	Pack unpacked objects in a repository.
-
 gitlink:git-rerere[1]::
 	Reuse recorded resolution of conflicted merges.
 
@@ -177,14 +172,11 @@ gitlink:git-shortlog[1]::
 gitlink:git-show[1]::
 	Show one commit log and its diff.
 
-gitlink:git-show-branch[1]::
-	Show branches and their commits.
-
 gitlink:git-status[1]::
 	Shows the working tree status.
 
-gitlink:git-verify-tag[1]::
-	Check the GPG signature of tag.
+gitlink:git-tag[1]::
+	Create or verify a tag object signed with GPG.
 
 gitlink:git-whatchanged[1]::
 	Shows commit logs and differences they introduce.
@@ -192,6 +184,7 @@ gitlink:git-whatchanged[1]::
 
 Ancillary Commands
 ~~~~~~~~~~~~~~~~~~
+
 Manipulators:
 
 gitlink:git-applypatch[1]::
@@ -200,6 +193,9 @@ gitlink:git-applypatch[1]::
 gitlink:git-archimport[1]::
 	Import an arch repository into git.
 
+gitlink:git-cherry-pick[1]::
+	Cherry-pick the effect of an existing commit.
+
 gitlink:git-convert-objects[1]::
 	Converts old-style git repository.
 
@@ -212,18 +208,18 @@ gitlink:git-cvsexportcommit[1]::
 gitlink:git-cvsserver[1]::
 	A CVS server emulator for git.
 
-gitlink:git-gc[1]::
-	Cleanup unnecessary files and optimize the local repository.
-
 gitlink:git-lost-found[1]::
 	Recover lost refs that luckily have not yet been pruned.
 
-gitlink:git-merge-one-file[1]::
-	The standard helper program to use with `git-merge-index`.
+gitlink:git-pack-refs[1]::
+	Pack heads and tags for efficient repository access.
 
 gitlink:git-prune[1]::
 	Prunes all unreachable objects from the object database.
 
+gitlink:git-repack[1]::
+	Pack unpacked objects in a repository.
+
 gitlink:git-quiltimport[1]::
 	Applies a quilt patchset onto the current branch.
 
@@ -239,18 +235,6 @@ gitlink:git-svn[1]::
 gitlink:git-svnimport[1]::
 	Import a SVN repository into git.
 
-gitlink:git-sh-setup[1]::
-	Common git shell script setup code.
-
-gitlink:git-symbolic-ref[1]::
-	Read and modify symbolic refs.
-
-gitlink:git-tag[1]::
-	Create or verify a tag object signed with GPG.
-
-gitlink:git-update-ref[1]::
-	Update the object name stored in a ref safely.
-
 
 Interrogators:
 
@@ -260,20 +244,14 @@ gitlink:git-annotate[1]::
 gitlink:git-blame[1]::
 	Find out where each line in a file came from.
 
-gitlink:git-check-ref-format[1]::
-	Make sure ref name is well formed.
-
 gitlink:git-cherry[1]::
 	Find commits not merged upstream.
 
-gitlink:git-count-objects[1]::
-	Count unpacked number of objects and their disk consumption.
-
-gitlink:git-daemon[1]::
-	A really simple server for git repositories.
+gitlink:git-describe[1]::
+	Show the most recent tag that is reachable from a commit.
 
-gitlink:git-fmt-merge-msg[1]::
-	Produce a merge commit message.
+gitlink:git-fsck-objects[1]::
+	Verifies the connectivity and validity of the objects in the database.
 
 gitlink:git-get-tar-commit-id[1]::
 	Extract commit ID from an archive created using git-tar-tree.
@@ -284,6 +262,9 @@ gitlink:git-imap-send[1]::
 gitlink:git-instaweb[1]::
 	Instantly browse your working repository in gitweb.
 
+gitlink:git-ls-remote[1]::
+	Shows references in a remote or local repository.
+
 gitlink:git-mailinfo[1]::
 	Extracts patch and authorship information from a single
 	e-mail message, optionally transliterating the commit
@@ -296,29 +277,17 @@ gitlink:git-mailsplit[1]::
 gitlink:git-merge-tree[1]::
 	Show three-way merge without touching index.
 
-gitlink:git-patch-id[1]::
-	Compute unique ID for a patch.
-
-gitlink:git-parse-remote[1]::
-	Routines to help parsing `$GIT_DIR/remotes/` files.
-
 gitlink:git-request-pull[1]::
 	git-request-pull.
 
-gitlink:git-rev-parse[1]::
-	Pick out and massage parameters.
-
-gitlink:git-runstatus[1]::
-	A helper for git-status and git-commit.
-
 gitlink:git-send-email[1]::
 	Send patch e-mails out of "format-patch --mbox" output.
 
-gitlink:git-symbolic-ref[1]::
-	Read and modify symbolic refs.
+gitlink:git-show-branch[1]::
+	Show branches and their commits.
 
-gitlink:git-stripspace[1]::
-	Filter out empty lines.
+gitlink:git-verify-tag[1]::
+	Check the GPG signature of tag.
 
 
 Low-level commands (plumbing)
@@ -337,6 +306,7 @@ repositories.
 
 Manipulation commands
 ~~~~~~~~~~~~~~~~~~~~~
+
 gitlink:git-apply[1]::
 	Reads a "diff -up1" or git generated patch file and
 	applies it to the working tree.
@@ -353,16 +323,15 @@ gitlink:git-hash-object[1]::
 gitlink:git-index-pack[1]::
 	Build pack idx file for an existing packed archive.
 
-gitlink:git-init[1]::
-	Creates an empty git repository, or reinitialize an
-	existing one.
-
 gitlink:git-merge-file[1]::
 	Runs a threeway merge.
 
 gitlink:git-merge-index[1]::
 	Runs a merge for files needing merging.
 
+gitlink:git-merge-one-file[1]::
+	The standard helper program to use with `git-merge-index`.
+
 gitlink:git-mktag[1]::
 	Creates a tag object.
 
@@ -381,12 +350,24 @@ gitlink:git-read-tree[1]::
 gitlink:git-repo-config[1]::
 	Get and set options in .git/config.
 
+gitlink:git-sh-setup[1]::
+	Common git shell script setup code.
+
+gitlink:git-stripspace[1]::
+	Filter out empty lines.
+
+gitlink:git-symbolic-ref[1]::
+	Read and modify symbolic refs.
+
 gitlink:git-unpack-objects[1]::
 	Unpacks objects out of a packed archive.
 
 gitlink:git-update-index[1]::
 	Registers files in the working tree to the index.
 
+gitlink:git-update-ref[1]::
+	Update the object name stored in a ref safely.
+
 gitlink:git-write-tree[1]::
 	Creates a tree from the index.
 
@@ -397,8 +378,11 @@ Interrogation commands
 gitlink:git-cat-file[1]::
 	Provide content or type/size information for repository objects.
 
-gitlink:git-describe[1]::
-	Show the most recent tag that is reachable from a commit.
+gitlink:git-check-ref-format[1]::
+	Make sure ref name is well formed.
+
+gitlink:git-count-objects[1]::
+	Count unpacked number of objects and their disk consumption.
 
 gitlink:git-diff-index[1]::
 	Compares content and mode of blobs between the index and repository.
@@ -415,8 +399,8 @@ gitlink:git-diff-tree[1]::
 gitlink:git-for-each-ref[1]::
 	Output information on each ref.
 
-gitlink:git-fsck-objects[1]::
-	Verifies the connectivity and validity of the objects in the database.
+gitlink:git-fmt-merge-msg[1]::
+	Produce a merge commit message.
 
 gitlink:git-ls-files[1]::
 	Information about files in the index and the working tree.
@@ -433,9 +417,18 @@ gitlink:git-name-rev[1]::
 gitlink:git-pack-redundant[1]::
 	Find redundant pack files.
 
+gitlink:git-patch-id[1]::
+	Compute unique ID for a patch.
+
 gitlink:git-rev-list[1]::
 	Lists commit objects in reverse chronological order.
 
+gitlink:git-rev-parse[1]::
+	Pick out and massage parameters.
+
+gitlink:git-runstatus[1]::
+	A helper for git-status and git-commit.
+
 gitlink:git-show-index[1]::
 	Displays contents of a pack idx file.
 
@@ -461,6 +454,9 @@ the working tree.
 Synching repositories
 ~~~~~~~~~~~~~~~~~~~~~
 
+gitlink:git-daemon[1]::
+	A really simple server for git repositories.
+
 gitlink:git-fetch-pack[1]::
 	Updates from a remote repository (engine for ssh and
 	local transport).
@@ -473,6 +469,9 @@ gitlink:git-local-fetch[1]::
 	Duplicates another git repository on a local system by
 	walking commit chain.
 
+gitlink:git-parse-remote[1]::
+	Routines to help parsing `$GIT_DIR/remotes/` files.
+
 gitlink:git-peek-remote[1]::
 	Lists references on a remote repository using
 	upload-pack protocol (engine for ssh and local

[PATCH] Documentation/git.txt: command re-classification

[Junio C Hamano]

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

Re: [PATCH] Documentation/git.txt: command re-classification

[Nicolas Pitre]

On Thu, 18 Jan 2007, Junio C Hamano wrote:

>  * 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.

OK.  But I think the following are still misclassified:

  git-rev-parse
  git-runstatus
  git-fsck-objects

> +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.

I think the "to put it another way" sentence is a bit confusing here.


Nicolas

Re: [PATCH] Documentation/git.txt: command re-classification

[Jakub Narebski]

Nicolas Pitre wrote:

>> +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.
> 
> I think the "to put it another way" sentence is a bit confusing here.

I think it should read "To put it another way, Porcelain level commands
are subject to change" instead of much less readable "To put it another way,
the interface to Plumbing commands are subject to change".
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH] Documentation/git.txt: command re-classification

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> OK.  But I think the following are still misclassified:
>
>   git-rev-parse
>   git-runstatus
>   git-fsck-objects

Thanks for proofreading.  runstatus should be a pure helper.  I
am not sure what rev-parse and fsck-objects are, but they are
not primary porcelain.  rev-parse could sit next to rev-list and
fsck-objects, I guess.

>> +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.
>
> I think the "to put it another way" sentence is a bit confusing here.

I agree.  What I wanted to say was the interface to plumbing is
sacred and we will not lightly change it without a very good
reason, while Porcelains are more or less "for breaking".

Better wording is certainly appreciated.

Re: [PATCH] Documentation/git.txt: command re-classification

[Nicolas Pitre]

On Fri, 19 Jan 2007, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > OK.  But I think the following are still misclassified:
> >
> >   git-rev-parse
> >   git-runstatus
> >   git-fsck-objects
> 
> Thanks for proofreading.  runstatus should be a pure helper.  I
> am not sure what rev-parse and fsck-objects are, but they are
> not primary porcelain.  rev-parse could sit next to rev-list and
> fsck-objects, I guess.

I don't think fsck-objects is really plumbing though.  I'd tag it as 
ancillaryinterrogators.

Also, having:

   git-am(1)
          Apply a series of patches from a mailbox.

   git-applymbox(1)
          Apply a series of patches in a mailbox.

looks a bit weird.  Why two commands with almost the same description?  
Maybe one of them could be relegated to ancillary?  Or even both of them 
to foreignscminterface?

Is git-show-branch really a primary command?

Then what about moving one of annotate or blame to the main section?

> >> +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.
> >
> > I think the "to put it another way" sentence is a bit confusing here.
> 
> I agree.  What I wanted to say was the interface to plumbing is
> sacred and we will not lightly change it without a very good
> reason, while Porcelains are more or less "for breaking".
> 
> Better wording is certainly appreciated.

I'd just drop the "to put it another way" entirely.


Nicolas

Re: [PATCH] Documentation/git.txt: command re-classification

[Jakub Narebski]

Nicolas Pitre wrote:

> Also, having:
> 
>    git-am(1)
>           Apply a series of patches from a mailbox.
> 
>    git-applymbox(1)
>           Apply a series of patches in a mailbox.
> 
> looks a bit weird.  Why two commands with almost the same description?  
> Maybe one of them could be relegated to ancillary?  Or even both of them 
> to foreignscminterface?

Because they are almost the same (same command, different interface).
git-applymbox is legacy for Linus.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH] Documentation/git.txt: command re-classification

[J. Bruce Fields]

On Fri, Jan 19, 2007 at 11:57:12PM +0100, Jakub Narebski wrote:
> Nicolas Pitre wrote:
> 
> > Also, having:
> > 
> >    git-am(1)
> >           Apply a series of patches from a mailbox.
> > 
> >    git-applymbox(1)
> >           Apply a series of patches in a mailbox.
> > 
> > looks a bit weird.  Why two commands with almost the same description?  
> > Maybe one of them could be relegated to ancillary?  Or even both of them 
> > to foreignscminterface?
> 
> Because they are almost the same (same command, different interface).
> git-applymbox is legacy for Linus.

Given how often this question is asked, maybe git-aplymbox should just
be removed from this and every other global list of commands.  Linus
(and whoever else is used to it) knows where to find it.

Unless there's really something it has that git-am doesn't.

--b.

Re: [PATCH] Documentation/git.txt: command re-classification

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> I don't think fsck-objects is really plumbing though.  I'd tag it as 
> ancillaryinterrogators.
>
> Also, having:
>
>    git-am(1)
>           Apply a series of patches from a mailbox.
>
>    git-applymbox(1)
>           Apply a series of patches in a mailbox.
>
> looks a bit weird.

I thought about that issue (also annotate vs blame).  I'm fine
with demoting applymbox to ancillary, perhaps with potential
future deprecation in mind (but that would be a separate topic).

annotate is already ancillary and blame also is.  Do you want to
promote one of them to mainporcelain?

> Is git-show-branch really a primary command?

Ah, I didn't notice that you wanted to move it out of
mainporcelain in your patch.

I personally use it quite often while juggling topics,
especially since I do not usually work inside X, but I'm fine
either way -- ancillaryinterrogators?

> I'd just drop the "to put it another way" entirely.

Ok, then how about this on top of what you saw on the list.


diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
index 9443ab3..4b76d19 100755
--- a/Documentation/cmd-list.perl
+++ b/Documentation/cmd-list.perl
@@ -62,7 +62,7 @@ __DATA__
 git-add                                 mainporcelain
 git-am                                  mainporcelain
 git-annotate                            ancillaryinterrogators
-git-applymbox                           mainporcelain
+git-applymbox                           ancillaryinterrogators
 git-applypatch                          purehelpers
 git-apply                               plumbingmanipulators
 git-archimport                          foreignscminterface
@@ -159,7 +159,7 @@ git-send-pack                           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                            purehelpers
diff --git a/Documentation/git.txt b/Documentation/git.txt
index ded48b5..9761de3 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -115,9 +115,9 @@ gitlink:git-read-tree[1].
 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.
+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

Re: [PATCH] Documentation/git.txt: command re-classification

[Nicolas Pitre]

On Fri, 19 Jan 2007, Junio C Hamano wrote:

> annotate is already ancillary and blame also is.  Do you want to
> promote one of them to mainporcelain?

I'd think so.

> > Is git-show-branch really a primary command?
> 
> Ah, I didn't notice that you wanted to move it out of
> mainporcelain in your patch.
> 
> I personally use it quite often while juggling topics,
> especially since I do not usually work inside X, but I'm fine
> either way -- ancillaryinterrogators?

Sure.

> Ok, then how about this on top of what you saw on the list.

I'd put fsck-objects in  ancillaryinterrogators.

Otherwise it looks fine.


Nicolas