{"thread":{"id":"6432","subject":"[PATCH] Documentation: revisit command qualification in git.txt","startedAt":"2007-01-18T22:25:41Z","lastAt":"2007-01-20T01:44:01Z","messageCount":10,"participants":["Nicolas Pitre","Junio C Hamano","Jakub Narebski","J. Bruce Fields"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"32024","messageId":"Pine.LNX.4.64.0701181713200.2577@xanadu.home","threadId":"6432","inReplyTo":null,"subject":"[PATCH] Documentation: revisit command qualification in git.txt","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2007-01-18T22:25:41Z","receivedAt":"2007-01-18T22:25:41Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"In particular, the \"Main porcelain commands\" section should focus on the \nminimum subset of obvious commands an average user is likely to ever \nneed.\n\nCommands that are not useful on their own should definitely be in the \nplumbing section.\n\nSigned-off-by: Nicolas Pitre \n---\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex a0bcef7..db83b69 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -102,9 +102,6 @@ gitlink:git-branch[1]::\n gitlink:git-checkout[1]::\n \tCheckout and switch to a branch.\n \n-gitlink:git-cherry-pick[1]::\n-\tCherry-pick the effect of an existing commit.\n-\n gitlink:git-clean[1]::\n \tRemove untracked files from the working tree.\n \n@@ -123,27 +120,28 @@ gitlink:git-fetch[1]::\n gitlink:git-format-patch[1]::\n \tPrepare patches for e-mail submission.\n \n+gitlink:git-gc[1]::\n+\tCleanup unnecessary files and optimize the local repository.\n+\n gitlink:git-grep[1]::\n \tPrint lines matching a pattern.\n \n+gitlink:git-init[1]::\n+\tCreates an empty git repository, or reinitialize an\n+\texisting one.\n+\n gitlink:gitk[1]::\n \tThe git repository browser.\n \n gitlink:git-log[1]::\n \tShows commit logs.\n \n-gitlink:git-ls-remote[1]::\n-\tShows references in a remote or local repository.\n-\n gitlink:git-merge[1]::\n \tGrand unified merge driver.\n \n gitlink:git-mv[1]::\n \tMove or rename a file, a directory, or a symlink.\n \n-gitlink:git-pack-refs[1]::\n-\tPack heads and tags for efficient repository access.\n-\n gitlink:git-pull[1]::\n \tFetch from and merge with a remote repository or a local branch.\n \n@@ -153,9 +151,6 @@ gitlink:git-push[1]::\n gitlink:git-rebase[1]::\n \tRebase local commits to the updated upstream head.\n \n-gitlink:git-repack[1]::\n-\tPack unpacked objects in a repository.\n-\n gitlink:git-rerere[1]::\n \tReuse recorded resolution of conflicted merges.\n \n@@ -177,14 +172,11 @@ gitlink:git-shortlog[1]::\n gitlink:git-show[1]::\n \tShow one commit log and its diff.\n \n-gitlink:git-show-branch[1]::\n-\tShow branches and their commits.\n-\n gitlink:git-status[1]::\n \tShows the working tree status.\n \n-gitlink:git-verify-tag[1]::\n-\tCheck the GPG signature of tag.\n+gitlink:git-tag[1]::\n+\tCreate or verify a tag object signed with GPG.\n \n gitlink:git-whatchanged[1]::\n \tShows commit logs and differences they introduce.\n@@ -192,6 +184,7 @@ gitlink:git-whatchanged[1]::\n \n Ancillary Commands\n ~~~~~~~~~~~~~~~~~~\n+\n Manipulators:\n \n gitlink:git-applypatch[1]::\n@@ -200,6 +193,9 @@ gitlink:git-applypatch[1]::\n gitlink:git-archimport[1]::\n \tImport an arch repository into git.\n \n+gitlink:git-cherry-pick[1]::\n+\tCherry-pick the effect of an existing commit.\n+\n gitlink:git-convert-objects[1]::\n \tConverts old-style git repository.\n \n@@ -212,18 +208,18 @@ gitlink:git-cvsexportcommit[1]::\n gitlink:git-cvsserver[1]::\n \tA CVS server emulator for git.\n \n-gitlink:git-gc[1]::\n-\tCleanup unnecessary files and optimize the local repository.\n-\n gitlink:git-lost-found[1]::\n \tRecover lost refs that luckily have not yet been pruned.\n \n-gitlink:git-merge-one-file[1]::\n-\tThe standard helper program to use with `git-merge-index`.\n+gitlink:git-pack-refs[1]::\n+\tPack heads and tags for efficient repository access.\n \n gitlink:git-prune[1]::\n \tPrunes all unreachable objects from the object database.\n \n+gitlink:git-repack[1]::\n+\tPack unpacked objects in a repository.\n+\n gitlink:git-quiltimport[1]::\n \tApplies a quilt patchset onto the current branch.\n \n@@ -239,18 +235,6 @@ gitlink:git-svn[1]::\n gitlink:git-svnimport[1]::\n \tImport a SVN repository into git.\n \n-gitlink:git-sh-setup[1]::\n-\tCommon git shell script setup code.\n-\n-gitlink:git-symbolic-ref[1]::\n-\tRead and modify symbolic refs.\n-\n-gitlink:git-tag[1]::\n-\tCreate or verify a tag object signed with GPG.\n-\n-gitlink:git-update-ref[1]::\n-\tUpdate the object name stored in a ref safely.\n-\n \n Interrogators:\n \n@@ -260,20 +244,14 @@ gitlink:git-annotate[1]::\n gitlink:git-blame[1]::\n \tFind out where each line in a file came from.\n \n-gitlink:git-check-ref-format[1]::\n-\tMake sure ref name is well formed.\n-\n gitlink:git-cherry[1]::\n \tFind commits not merged upstream.\n \n-gitlink:git-count-objects[1]::\n-\tCount unpacked number of objects and their disk consumption.\n-\n-gitlink:git-daemon[1]::\n-\tA really simple server for git repositories.\n+gitlink:git-describe[1]::\n+\tShow the most recent tag that is reachable from a commit.\n \n-gitlink:git-fmt-merge-msg[1]::\n-\tProduce a merge commit message.\n+gitlink:git-fsck-objects[1]::\n+\tVerifies the connectivity and validity of the objects in the database.\n \n gitlink:git-get-tar-commit-id[1]::\n \tExtract commit ID from an archive created using git-tar-tree.\n@@ -284,6 +262,9 @@ gitlink:git-imap-send[1]::\n gitlink:git-instaweb[1]::\n \tInstantly browse your working repository in gitweb.\n \n+gitlink:git-ls-remote[1]::\n+\tShows references in a remote or local repository.\n+\n gitlink:git-mailinfo[1]::\n \tExtracts patch and authorship information from a single\n \te-mail message, optionally transliterating the commit\n@@ -296,29 +277,17 @@ gitlink:git-mailsplit[1]::\n gitlink:git-merge-tree[1]::\n \tShow three-way merge without touching index.\n \n-gitlink:git-patch-id[1]::\n-\tCompute unique ID for a patch.\n-\n-gitlink:git-parse-remote[1]::\n-\tRoutines to help parsing `$GIT_DIR/remotes/` files.\n-\n gitlink:git-request-pull[1]::\n \tgit-request-pull.\n \n-gitlink:git-rev-parse[1]::\n-\tPick out and massage parameters.\n-\n-gitlink:git-runstatus[1]::\n-\tA helper for git-status and git-commit.\n-\n gitlink:git-send-email[1]::\n \tSend patch e-mails out of \"format-patch --mbox\" output.\n \n-gitlink:git-symbolic-ref[1]::\n-\tRead and modify symbolic refs.\n+gitlink:git-show-branch[1]::\n+\tShow branches and their commits.\n \n-gitlink:git-stripspace[1]::\n-\tFilter out empty lines.\n+gitlink:git-verify-tag[1]::\n+\tCheck the GPG signature of tag.\n \n \n Low-level commands (plumbing)\n@@ -337,6 +306,7 @@ repositories.\n \n Manipulation commands\n ~~~~~~~~~~~~~~~~~~~~~\n+\n gitlink:git-apply[1]::\n \tReads a \"diff -up1\" or git generated patch file and\n \tapplies it to the working tree.\n@@ -353,16 +323,15 @@ gitlink:git-hash-object[1]::\n gitlink:git-index-pack[1]::\n \tBuild pack idx file for an existing packed archive.\n \n-gitlink:git-init[1]::\n-\tCreates an empty git repository, or reinitialize an\n-\texisting one.\n-\n gitlink:git-merge-file[1]::\n \tRuns a threeway merge.\n \n gitlink:git-merge-index[1]::\n \tRuns a merge for files needing merging.\n \n+gitlink:git-merge-one-file[1]::\n+\tThe standard helper program to use with `git-merge-index`.\n+\n gitlink:git-mktag[1]::\n \tCreates a tag object.\n \n@@ -381,12 +350,24 @@ gitlink:git-read-tree[1]::\n gitlink:git-repo-config[1]::\n \tGet and set options in .git/config.\n \n+gitlink:git-sh-setup[1]::\n+\tCommon git shell script setup code.\n+\n+gitlink:git-stripspace[1]::\n+\tFilter out empty lines.\n+\n+gitlink:git-symbolic-ref[1]::\n+\tRead and modify symbolic refs.\n+\n gitlink:git-unpack-objects[1]::\n \tUnpacks objects out of a packed archive.\n \n gitlink:git-update-index[1]::\n \tRegisters files in the working tree to the index.\n \n+gitlink:git-update-ref[1]::\n+\tUpdate the object name stored in a ref safely.\n+\n gitlink:git-write-tree[1]::\n \tCreates a tree from the index.\n \n@@ -397,8 +378,11 @@ Interrogation commands\n gitlink:git-cat-file[1]::\n \tProvide content or type/size information for repository objects.\n \n-gitlink:git-describe[1]::\n-\tShow the most recent tag that is reachable from a commit.\n+gitlink:git-check-ref-format[1]::\n+\tMake sure ref name is well formed.\n+\n+gitlink:git-count-objects[1]::\n+\tCount unpacked number of objects and their disk consumption.\n \n gitlink:git-diff-index[1]::\n \tCompares content and mode of blobs between the index and repository.\n@@ -415,8 +399,8 @@ gitlink:git-diff-tree[1]::\n gitlink:git-for-each-ref[1]::\n \tOutput information on each ref.\n \n-gitlink:git-fsck-objects[1]::\n-\tVerifies the connectivity and validity of the objects in the database.\n+gitlink:git-fmt-merge-msg[1]::\n+\tProduce a merge commit message.\n \n gitlink:git-ls-files[1]::\n \tInformation about files in the index and the working tree.\n@@ -433,9 +417,18 @@ gitlink:git-name-rev[1]::\n gitlink:git-pack-redundant[1]::\n \tFind redundant pack files.\n \n+gitlink:git-patch-id[1]::\n+\tCompute unique ID for a patch.\n+\n gitlink:git-rev-list[1]::\n \tLists commit objects in reverse chronological order.\n \n+gitlink:git-rev-parse[1]::\n+\tPick out and massage parameters.\n+\n+gitlink:git-runstatus[1]::\n+\tA helper for git-status and git-commit.\n+\n gitlink:git-show-index[1]::\n \tDisplays contents of a pack idx file.\n \n@@ -461,6 +454,9 @@ the working tree.\n Synching repositories\n ~~~~~~~~~~~~~~~~~~~~~\n \n+gitlink:git-daemon[1]::\n+\tA really simple server for git repositories.\n+\n gitlink:git-fetch-pack[1]::\n \tUpdates from a remote repository (engine for ssh and\n \tlocal transport).\n@@ -473,6 +469,9 @@ gitlink:git-local-fetch[1]::\n \tDuplicates another git repository on a local system by\n \twalking commit chain.\n \n+gitlink:git-parse-remote[1]::\n+\tRoutines to help parsing `$GIT_DIR/remotes/` files.\n+\n gitlink:git-peek-remote[1]::\n \tLists references on a remote repository using\n \tupload-pack protocol (engine for ssh and local\n"},{"id":"32034","messageId":"7v1wlrle61.fsf@assigned-by-dhcp.cox.net","threadId":"6432","inReplyTo":"Pine.LNX.4.64.0701181713200.2577@xanadu.home","subject":"[PATCH] Documentation/git.txt: command re-classification","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2007-01-19T06:32:38Z","receivedAt":"2007-01-19T06:32:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"This adds two new classes (pure-helpers and \"Interacting with\nOthers\") to the command list in the main manual page. The\nlatter class is primarily about foreign SCM interface and is\nplaced before low-level (plumbing) commands.\n\nAlso it promotes a handful commands to mainporcelain category\nwhile demotes some others.\n\nSigned-off-by: Junio C Hamano \n---\n\n * I unfortunately had to drop your patch on the floor, because\n I was cooking a few patches to automate the maintenance of\n the command list (which are now in 'master' and the product is\n being served at www.kernel.org/pub/software/scm/git/docs/),\n which majorly conflicted with your work.\n\n So here is a counterproposal; I moved commands across groups\n after looking at what your patch did, but classified some of\n them differently.\n\n Documentation/Makefile | 5 ++-\n Documentation/cmd-list.perl | 88 ++++++++++++++++++++++---------------------\n Documentation/git.txt | 35 ++++++++++++++++-\n 3 files changed, 83 insertions(+), 45 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 96755ad..19b2505 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -76,7 +76,10 @@ cmds_txt = cmds-ancillaryinterrogators.txt \\\n \tcmds-mainporcelain.txt \\\n \tcmds-plumbinginterrogators.txt \\\n \tcmds-plumbingmanipulators.txt \\\n-\tcmds-synchingrepositories.txt\n+\tcmds-synchingrepositories.txt \\\n+\tcmds-synchelpers.txt \\\n+\tcmds-purehelpers.txt \\\n+\tcmds-foreignscminterface.txt\n \n $(cmds_txt): cmd-list.perl $(MAN1_TXT) $(MAN7_TXT)\n \tperl ./cmd-list.perl\ndiff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl\nindex 5680dcb..9443ab3 100755\n--- a/Documentation/cmd-list.perl\n+++ b/Documentation/cmd-list.perl\n@@ -45,7 +45,10 @@ for my $cat (qw(ancillaryinterrogators\n \t\tmainporcelain\n \t\tplumbinginterrogators\n \t\tplumbingmanipulators\n-\t\tsynchingrepositories)) {\n+\t\tsynchingrepositories\n+\t\tforeignscminterface\n+\t\tpurehelpers\n+\t\tsynchelpers)) {\n \tmy $out = \"cmds-$cat.txt\";\n \topen O, '>', \"$out+\" or die \"Cannot open output file $out+\";\n \tfor (@{$cmds{$cat}}) {\n@@ -60,9 +63,9 @@ git-add mainporcelain\n git-am mainporcelain\n git-annotate ancillaryinterrogators\n git-applymbox mainporcelain\n-git-applypatch ancillarymanipulators\n+git-applypatch purehelpers\n git-apply plumbingmanipulators\n-git-archimport ancillarymanipulators\n+git-archimport foreignscminterface\n git-archive mainporcelain\n git-bisect mainporcelain\n git-blame ancillaryinterrogators\n@@ -70,7 +73,7 @@ git-branch mainporcelain\n git-cat-file plumbinginterrogators\n git-checkout-index plumbingmanipulators\n git-checkout mainporcelain\n-git-check-ref-format ancillaryinterrogators\n+git-check-ref-format purehelpers\n git-cherry ancillaryinterrogators\n git-cherry-pick mainporcelain\n git-clean mainporcelain\n@@ -79,11 +82,11 @@ git-commit mainporcelain\n git-commit-tree plumbingmanipulators\n git-convert-objects ancillarymanipulators\n git-count-objects ancillaryinterrogators\n-git-cvsexportcommit ancillarymanipulators\n-git-cvsimport ancillarymanipulators\n-git-cvsserver ancillarymanipulators\n-git-daemon ancillaryinterrogators\n-git-describe plumbinginterrogators\n+git-cvsexportcommit foreignscminterface\n+git-cvsimport foreignscminterface\n+git-cvsserver foreignscminterface\n+git-daemon synchingrepositories\n+git-describe mainporcelain\n git-diff-files plumbinginterrogators\n git-diff-index plumbinginterrogators\n git-diff mainporcelain\n@@ -91,34 +94,34 @@ git-diff-stages plumbinginterrogators\n git-diff-tree plumbinginterrogators\n git-fetch mainporcelain\n git-fetch-pack synchingrepositories\n-git-fmt-merge-msg ancillaryinterrogators\n+git-fmt-merge-msg purehelpers\n git-for-each-ref plumbinginterrogators\n git-format-patch mainporcelain\n git-fsck-objects plumbinginterrogators\n-git-gc ancillarymanipulators\n+git-gc mainporcelain\n git-get-tar-commit-id ancillaryinterrogators\n git-grep mainporcelain\n git-hash-object plumbingmanipulators\n-git-http-fetch synchingrepositories\n-git-http-push synchingrepositories\n-git-imap-send ancillaryinterrogators\n+git-http-fetch synchelpers\n+git-http-push synchelpers\n+git-imap-send foreignscminterface\n git-index-pack plumbingmanipulators\n-git-init plumbingmanipulators\n+git-init mainporcelain\n git-instaweb ancillaryinterrogators\n gitk mainporcelain\n git-local-fetch synchingrepositories\n git-log mainporcelain\n git-lost-found ancillarymanipulators\n git-ls-files plumbinginterrogators\n-git-ls-remote mainporcelain\n+git-ls-remote plumbinginterrogators\n git-ls-tree plumbinginterrogators\n-git-mailinfo ancillaryinterrogators\n-git-mailsplit ancillaryinterrogators\n+git-mailinfo purehelpers\n+git-mailsplit purehelpers\n git-merge-base plumbinginterrogators\n git-merge-file plumbingmanipulators\n git-merge-index plumbingmanipulators\n git-merge mainporcelain\n-git-merge-one-file ancillarymanipulators\n+git-merge-one-file purehelpers\n git-merge-tree ancillaryinterrogators\n git-mktag plumbingmanipulators\n git-mktree plumbingmanipulators\n@@ -126,24 +129,24 @@ git-mv mainporcelain\n git-name-rev plumbinginterrogators\n git-pack-objects plumbingmanipulators\n git-pack-redundant plumbinginterrogators\n-git-pack-refs mainporcelain\n-git-parse-remote ancillaryinterrogators\n-git-patch-id ancillaryinterrogators\n-git-peek-remote synchingrepositories\n+git-pack-refs ancillarymanipulators\n+git-parse-remote synchelpers\n+git-patch-id purehelpers\n+git-peek-remote purehelpers\n git-prune ancillarymanipulators\n git-prune-packed plumbingmanipulators\n git-pull mainporcelain\n git-push mainporcelain\n-git-quiltimport ancillarymanipulators\n+git-quiltimport foreignscminterface\n git-read-tree plumbingmanipulators\n git-rebase mainporcelain\n-git-receive-pack synchingrepositories\n+git-receive-pack synchelpers\n git-reflog ancillarymanipulators\n git-relink ancillarymanipulators\n-git-repack mainporcelain\n-git-repo-config plumbingmanipulators\n-git-request-pull ancillaryinterrogators\n-git-rerere mainporcelain\n+git-repack ancillarymanipulators\n+git-repo-config ancillarymanipulators\n+git-request-pull foreignscminterface\n+git-rerere ancillaryinterrogators\n git-reset mainporcelain\n git-resolve mainporcelain\n git-revert mainporcelain\n@@ -151,34 +154,33 @@ git-rev-list plumbinginterrogators\n git-rev-parse ancillaryinterrogators\n git-rm mainporcelain\n git-runstatus ancillaryinterrogators\n-git-send-email ancillaryinterrogators\n+git-send-email foreignscminterface\n git-send-pack synchingrepositories\n-git-shell synchingrepositories\n+git-shell synchelpers\n git-shortlog mainporcelain\n git-show mainporcelain\n git-show-branch mainporcelain\n git-show-index plumbinginterrogators\n git-show-ref plumbinginterrogators\n-git-sh-setup ancillarymanipulators\n+git-sh-setup purehelpers\n git-ssh-fetch synchingrepositories\n git-ssh-upload synchingrepositories\n git-status mainporcelain\n-git-stripspace ancillaryinterrogators\n-git-svn ancillarymanipulators\n-git-svnimport ancillarymanipulators\n-git-symbolic-ref ancillaryinterrogators\n-git-symbolic-ref ancillarymanipulators\n-git-tag ancillarymanipulators\n+git-stripspace purehelpers\n+git-svn foreignscminterface\n+git-svnimport foreignscminterface\n+git-symbolic-ref plumbingmanipulators\n+git-tag mainporcelain\n git-tar-tree plumbinginterrogators\n git-unpack-file plumbinginterrogators\n git-unpack-objects plumbingmanipulators\n git-update-index plumbingmanipulators\n-git-update-ref ancillarymanipulators\n+git-update-ref plumbingmanipulators\n git-update-server-info synchingrepositories\n-git-upload-archive synchingrepositories\n-git-upload-pack synchingrepositories\n+git-upload-archive synchelpers\n+git-upload-pack synchelpers\n git-var plumbinginterrogators\n git-verify-pack plumbinginterrogators\n-git-verify-tag mainporcelain\n-git-whatchanged mainporcelain\n+git-verify-tag ancillaryinterrogators\n+git-whatchanged ancillaryinterrogators\n git-write-tree plumbingmanipulators\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex ac22206..ded48b5 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -93,6 +93,16 @@ Interrogators:\n \n include::cmds-ancillaryinterrogators.txt[]\n \n+\n+Interacting with Others\n+~~~~~~~~~~~~~~~~~~~~~~~\n+\n+These commands are to interact with foreign SCM and with other\n+people via patch over e-mail.\n+\n+include::cmds-foreignscminterface.txt[]\n+\n+\n Low-level commands (plumbing)\n -----------------------------\n \n@@ -102,11 +112,20 @@ development of alternative porcelains. Developers of such porcelains\n might start by reading about gitlink:git-update-index[1] and\n gitlink:git-read-tree[1].\n \n-We divide the low-level commands into commands that manipulate objects (in\n+The interface (input, output, set of options and the semantics)\n+to these low-level commands are meant to be a lot more stable\n+than Porcelain level commands, because these commands are\n+primarily for scripted use. To put it another way, the\n+interface to Plumbing commands are subject to change in order to\n+improve the end user experience.\n+\n+The following description divides\n+the low-level commands into commands that manipulate objects (in\n the repository, index, and working tree), commands that interrogate and\n compare objects, and commands that move objects and references between\n repositories.\n \n+\n Manipulation commands\n ~~~~~~~~~~~~~~~~~~~~~\n \n@@ -127,6 +146,20 @@ Synching repositories\n \n include::cmds-synchingrepositories.txt[]\n \n+The following are helper programs used by the above; end users\n+typically do not use them directly.\n+\n+include::cmds-synchelpers.txt[]\n+\n+\n+Internal helper commands\n+~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+These are internal helper commands used by other commands; end\n+users typically do not use them directly.\n+\n+include::cmds-purehelpers.txt[]\n+\n \n Configuration Mechanism\n -----------------------\n-- \n1.5.0.rc1.g72fe\n"},{"id":"32089","messageId":"Pine.LNX.4.64.0701191437450.3011@xanadu.home","threadId":"6432","inReplyTo":"7v1wlrle61.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Documentation/git.txt: command re-classification","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2007-01-19T22:08:53Z","receivedAt":"2007-01-19T22:08:53Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Thu, 18 Jan 2007, Junio C Hamano wrote:\n\n> * I unfortunately had to drop your patch on the floor, because\n> I was cooking a few patches to automate the maintenance of\n> the command list (which are now in 'master' and the product is\n> being served at www.kernel.org/pub/software/scm/git/docs/),\n> which majorly conflicted with your work.\n> \n> So here is a counterproposal; I moved commands across groups\n> after looking at what your patch did, but classified some of\n> them differently.\n\nOK. But I think the following are still misclassified:\n\n git-rev-parse\n git-runstatus\n git-fsck-objects\n\n> +The interface (input, output, set of options and the semantics)\n> +to these low-level commands are meant to be a lot more stable\n> +than Porcelain level commands, because these commands are\n> +primarily for scripted use. To put it another way, the\n> +interface to Plumbing commands are subject to change in order to\n> +improve the end user experience.\n\nI think the \"to put it another way\" sentence is a bit confusing here.\n\n\nNicolas\n"},{"id":"32091","messageId":"eorg2u$f1o$2@sea.gmane.org","threadId":"6432","inReplyTo":"Pine.LNX.4.64.0701191437450.3011@xanadu.home","subject":"Re: [PATCH] Documentation/git.txt: command re-classification","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-01-19T22:18:47Z","receivedAt":"2007-01-19T22:18:47Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Nicolas Pitre wrote:\n\n>> +The interface (input, output, set of options and the semantics)\n>> +to these low-level commands are meant to be a lot more stable\n>> +than Porcelain level commands, because these commands are\n>> +primarily for scripted use.  To put it another way, the\n>> +interface to Plumbing commands are subject to change in order to\n>> +improve the end user experience.\n> \n> I think the \"to put it another way\" sentence is a bit confusing here.\n\nI think it should read \"To put it another way, Porcelain level commands\nare subject to change\" instead of much less readable \"To put it another way,\nthe interface to Plumbing commands are subject to change\".\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n"},{"id":"32092","messageId":"7vbqkufyhy.fsf@assigned-by-dhcp.cox.net","threadId":"6432","inReplyTo":"Pine.LNX.4.64.0701191437450.3011@xanadu.home","subject":"Re: [PATCH] Documentation/git.txt: command re-classification","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2007-01-19T22:22:17Z","receivedAt":"2007-01-19T22:22:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nicolas Pitre writes:\n\n> OK. But I think the following are still misclassified:\n>\n> git-rev-parse\n> git-runstatus\n> git-fsck-objects\n\nThanks for proofreading. runstatus should be a pure helper. I\nam not sure what rev-parse and fsck-objects are, but they are\nnot primary porcelain. rev-parse could sit next to rev-list and\nfsck-objects, I guess.\n\n>> +The interface (input, output, set of options and the semantics)\n>> +to these low-level commands are meant to be a lot more stable\n>> +than Porcelain level commands, because these commands are\n>> +primarily for scripted use. To put it another way, the\n>> +interface to Plumbing commands are subject to change in order to\n>> +improve the end user experience.\n>\n> I think the \"to put it another way\" sentence is a bit confusing here.\n\nI agree. What I wanted to say was the interface to plumbing is\nsacred and we will not lightly change it without a very good\nreason, while Porcelains are more or less \"for breaking\".\n\nBetter wording is certainly appreciated.\n"},{"id":"32097","messageId":"Pine.LNX.4.64.0701191729060.3011@xanadu.home","threadId":"6432","inReplyTo":"7vbqkufyhy.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Documentation/git.txt: command re-classification","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2007-01-19T22:44:58Z","receivedAt":"2007-01-19T22:44:58Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Fri, 19 Jan 2007, Junio C Hamano wrote:\n\n> Nicolas Pitre writes:\n> \n> > OK. But I think the following are still misclassified:\n> >\n> > git-rev-parse\n> > git-runstatus\n> > git-fsck-objects\n> \n> Thanks for proofreading. runstatus should be a pure helper. I\n> am not sure what rev-parse and fsck-objects are, but they are\n> not primary porcelain. rev-parse could sit next to rev-list and\n> fsck-objects, I guess.\n\nI don't think fsck-objects is really plumbing though. I'd tag it as \nancillaryinterrogators.\n\nAlso, having:\n\n git-am(1)\n Apply a series of patches from a mailbox.\n\n git-applymbox(1)\n Apply a series of patches in a mailbox.\n\nlooks a bit weird. Why two commands with almost the same description? \nMaybe one of them could be relegated to ancillary? Or even both of them \nto foreignscminterface?\n\nIs git-show-branch really a primary command?\n\nThen what about moving one of annotate or blame to the main section?\n\n> >> +The interface (input, output, set of options and the semantics) \n> >> +to these low-level commands are meant to be a lot more stable \n> >> +than Porcelain level commands, because these commands are \n> >> +primarily for scripted use. To put it another way, the +interface \n> >> to Plumbing commands are subject to change in order to +improve the \n> >> end user experience.\n> >\n> > I think the \"to put it another way\" sentence is a bit confusing here.\n> \n> I agree. What I wanted to say was the interface to plumbing is\n> sacred and we will not lightly change it without a very good\n> reason, while Porcelains are more or less \"for breaking\".\n> \n> Better wording is certainly appreciated.\n\nI'd just drop the \"to put it another way\" entirely.\n\n\nNicolas\n"},{"id":"32099","messageId":"eoriau$n97$1@sea.gmane.org","threadId":"6432","inReplyTo":"Pine.LNX.4.64.0701191729060.3011@xanadu.home","subject":"Re: [PATCH] Documentation/git.txt: command re-classification","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2007-01-19T22:57:12Z","receivedAt":"2007-01-19T22:57:12Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Nicolas Pitre wrote:\n\n> Also, having:\n> \n>    git-am(1)\n>           Apply a series of patches from a mailbox.\n> \n>    git-applymbox(1)\n>           Apply a series of patches in a mailbox.\n> \n> looks a bit weird.  Why two commands with almost the same description?  \n> Maybe one of them could be relegated to ancillary?  Or even both of them \n> to foreignscminterface?\n\nBecause they are almost the same (same command, different interface).\ngit-applymbox is legacy for Linus.\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n"},{"id":"32100","messageId":"20070119225920.GA26442@fieldses.org","threadId":"6432","inReplyTo":"eoriau$n97$1@sea.gmane.org","subject":"Re: [PATCH] Documentation/git.txt: command re-classification","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2007-01-19T22:59:20Z","receivedAt":"2007-01-19T22:59:20Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Fri, Jan 19, 2007 at 11:57:12PM +0100, Jakub Narebski wrote:\n> Nicolas Pitre wrote:\n> \n> > Also, having:\n> > \n> >    git-am(1)\n> >           Apply a series of patches from a mailbox.\n> > \n> >    git-applymbox(1)\n> >           Apply a series of patches in a mailbox.\n> > \n> > looks a bit weird.  Why two commands with almost the same description?  \n> > Maybe one of them could be relegated to ancillary?  Or even both of them \n> > to foreignscminterface?\n> \n> Because they are almost the same (same command, different interface).\n> git-applymbox is legacy for Linus.\n\nGiven how often this question is asked, maybe git-aplymbox should just\nbe removed from this and every other global list of commands. Linus\n(and whoever else is used to it) knows where to find it.\n\nUnless there's really something it has that git-am doesn't.\n\n--b.\n"},{"id":"32101","messageId":"7vps9aeghh.fsf@assigned-by-dhcp.cox.net","threadId":"6432","inReplyTo":"Pine.LNX.4.64.0701191729060.3011@xanadu.home","subject":"Re: [PATCH] Documentation/git.txt: command re-classification","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2007-01-19T23:36:42Z","receivedAt":"2007-01-19T23:36:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nicolas Pitre writes:\n\n> I don't think fsck-objects is really plumbing though. I'd tag it as \n> ancillaryinterrogators.\n>\n> Also, having:\n>\n> git-am(1)\n> Apply a series of patches from a mailbox.\n>\n> git-applymbox(1)\n> Apply a series of patches in a mailbox.\n>\n> looks a bit weird.\n\nI thought about that issue (also annotate vs blame). I'm fine\nwith demoting applymbox to ancillary, perhaps with potential\nfuture deprecation in mind (but that would be a separate topic).\n\nannotate is already ancillary and blame also is. Do you want to\npromote one of them to mainporcelain?\n\n> Is git-show-branch really a primary command?\n\nAh, I didn't notice that you wanted to move it out of\nmainporcelain in your patch.\n\nI personally use it quite often while juggling topics,\nespecially since I do not usually work inside X, but I'm fine\neither way -- ancillaryinterrogators?\n\n> I'd just drop the \"to put it another way\" entirely.\n\nOk, then how about this on top of what you saw on the list.\n\n\ndiff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl\nindex 9443ab3..4b76d19 100755\n--- a/Documentation/cmd-list.perl\n+++ b/Documentation/cmd-list.perl\n@@ -62,7 +62,7 @@ __DATA__\n git-add mainporcelain\n git-am mainporcelain\n git-annotate ancillaryinterrogators\n-git-applymbox mainporcelain\n+git-applymbox ancillaryinterrogators\n git-applypatch purehelpers\n git-apply plumbingmanipulators\n git-archimport foreignscminterface\n@@ -159,7 +159,7 @@ git-send-pack synchingrepositories\n git-shell synchelpers\n git-shortlog mainporcelain\n git-show mainporcelain\n-git-show-branch mainporcelain\n+git-show-branch ancillaryinterrogators\n git-show-index plumbinginterrogators\n git-show-ref plumbinginterrogators\n git-sh-setup purehelpers\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex ded48b5..9761de3 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -115,9 +115,9 @@ gitlink:git-read-tree[1].\n The interface (input, output, set of options and the semantics)\n to these low-level commands are meant to be a lot more stable\n than Porcelain level commands, because these commands are\n-primarily for scripted use. To put it another way, the\n-interface to Plumbing commands are subject to change in order to\n-improve the end user experience.\n+primarily for scripted use. The interface to Porcelain commands\n+on the other hand are subject to change in order to improve the\n+end user experience.\n \n The following description divides\n the low-level commands into commands that manipulate objects (in\n"},{"id":"32129","messageId":"Pine.LNX.4.64.0701192040130.3011@xanadu.home","threadId":"6432","inReplyTo":"7vps9aeghh.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Documentation/git.txt: command re-classification","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2007-01-20T01:44:01Z","receivedAt":"2007-01-20T01:44:01Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Fri, 19 Jan 2007, Junio C Hamano wrote:\n\n> annotate is already ancillary and blame also is. Do you want to\n> promote one of them to mainporcelain?\n\nI'd think so.\n\n> > Is git-show-branch really a primary command?\n> \n> Ah, I didn't notice that you wanted to move it out of\n> mainporcelain in your patch.\n> \n> I personally use it quite often while juggling topics,\n> especially since I do not usually work inside X, but I'm fine\n> either way -- ancillaryinterrogators?\n\nSure.\n\n> Ok, then how about this on top of what you saw on the list.\n\nI'd put fsck-objects in ancillaryinterrogators.\n\nOtherwise it looks fine.\n\n\nNicolas\n"}]}