Skip to content

Commit 89bf207

Browse files
author
Junio C Hamano
committed
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>
1 parent be93fc0 commit 89bf207

File tree

3 files changed

+86
-48
lines changed

3 files changed

+86
-48
lines changed

‎Documentation/Makefile‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,10 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
7676
cmds-mainporcelain.txt \
7777
cmds-plumbinginterrogators.txt \
7878
cmds-plumbingmanipulators.txt \
79-
cmds-synchingrepositories.txt
79+
cmds-synchingrepositories.txt \
80+
cmds-synchelpers.txt \
81+
cmds-purehelpers.txt \
82+
cmds-foreignscminterface.txt
8083

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

‎Documentation/cmd-list.perl‎

Lines changed: 48 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,10 @@ sub format_one {
4545
mainporcelain
4646
plumbinginterrogators
4747
plumbingmanipulators
48-
synchingrepositories)) {
48+
synchingrepositories
49+
foreignscminterface
50+
purehelpers
51+
synchelpers)) {
4952
my $out = "cmds-$cat.txt";
5053
open O, '>', "$out+" or die "Cannot open output file $out+";
5154
for (@{$cmds{$cat}}) {
@@ -59,18 +62,18 @@ sub format_one {
5962
git-add mainporcelain
6063
git-am mainporcelain
6164
git-annotate ancillaryinterrogators
62-
git-applymbox mainporcelain
63-
git-applypatch ancillarymanipulators
65+
git-applymbox ancillaryinterrogators
66+
git-applypatch purehelpers
6467
git-apply plumbingmanipulators
65-
git-archimport ancillarymanipulators
68+
git-archimport foreignscminterface
6669
git-archive mainporcelain
6770
git-bisect mainporcelain
6871
git-blame ancillaryinterrogators
6972
git-branch mainporcelain
7073
git-cat-file plumbinginterrogators
7174
git-checkout-index plumbingmanipulators
7275
git-checkout mainporcelain
73-
git-check-ref-format ancillaryinterrogators
76+
git-check-ref-format purehelpers
7477
git-cherry ancillaryinterrogators
7578
git-cherry-pick mainporcelain
7679
git-clean mainporcelain
@@ -79,106 +82,105 @@ sub format_one {
7982
git-commit-tree plumbingmanipulators
8083
git-convert-objects ancillarymanipulators
8184
git-count-objects ancillaryinterrogators
82-
git-cvsexportcommit ancillarymanipulators
83-
git-cvsimport ancillarymanipulators
84-
git-cvsserver ancillarymanipulators
85-
git-daemon ancillaryinterrogators
86-
git-describe plumbinginterrogators
85+
git-cvsexportcommit foreignscminterface
86+
git-cvsimport foreignscminterface
87+
git-cvsserver foreignscminterface
88+
git-daemon synchingrepositories
89+
git-describe mainporcelain
8790
git-diff-files plumbinginterrogators
8891
git-diff-index plumbinginterrogators
8992
git-diff mainporcelain
9093
git-diff-stages plumbinginterrogators
9194
git-diff-tree plumbinginterrogators
9295
git-fetch mainporcelain
9396
git-fetch-pack synchingrepositories
94-
git-fmt-merge-msg ancillaryinterrogators
97+
git-fmt-merge-msg purehelpers
9598
git-for-each-ref plumbinginterrogators
9699
git-format-patch mainporcelain
97-
git-fsck-objects plumbinginterrogators
98-
git-gc ancillarymanipulators
100+
git-fsck-objects ancillaryinterrogators
101+
git-gc mainporcelain
99102
git-get-tar-commit-id ancillaryinterrogators
100103
git-grep mainporcelain
101104
git-hash-object plumbingmanipulators
102-
git-http-fetch synchingrepositories
103-
git-http-push synchingrepositories
104-
git-imap-send ancillaryinterrogators
105+
git-http-fetch synchelpers
106+
git-http-push synchelpers
107+
git-imap-send foreignscminterface
105108
git-index-pack plumbingmanipulators
106-
git-init plumbingmanipulators
109+
git-init mainporcelain
107110
git-instaweb ancillaryinterrogators
108111
gitk mainporcelain
109112
git-local-fetch synchingrepositories
110113
git-log mainporcelain
111114
git-lost-found ancillarymanipulators
112115
git-ls-files plumbinginterrogators
113-
git-ls-remote mainporcelain
116+
git-ls-remote plumbinginterrogators
114117
git-ls-tree plumbinginterrogators
115-
git-mailinfo ancillaryinterrogators
116-
git-mailsplit ancillaryinterrogators
118+
git-mailinfo purehelpers
119+
git-mailsplit purehelpers
117120
git-merge-base plumbinginterrogators
118121
git-merge-file plumbingmanipulators
119122
git-merge-index plumbingmanipulators
120123
git-merge mainporcelain
121-
git-merge-one-file ancillarymanipulators
124+
git-merge-one-file purehelpers
122125
git-merge-tree ancillaryinterrogators
123126
git-mktag plumbingmanipulators
124127
git-mktree plumbingmanipulators
125128
git-mv mainporcelain
126129
git-name-rev plumbinginterrogators
127130
git-pack-objects plumbingmanipulators
128131
git-pack-redundant plumbinginterrogators
129-
git-pack-refs mainporcelain
130-
git-parse-remote ancillaryinterrogators
131-
git-patch-id ancillaryinterrogators
132-
git-peek-remote synchingrepositories
132+
git-pack-refs ancillarymanipulators
133+
git-parse-remote synchelpers
134+
git-patch-id purehelpers
135+
git-peek-remote purehelpers
133136
git-prune ancillarymanipulators
134137
git-prune-packed plumbingmanipulators
135138
git-pull mainporcelain
136139
git-push mainporcelain
137-
git-quiltimport ancillarymanipulators
140+
git-quiltimport foreignscminterface
138141
git-read-tree plumbingmanipulators
139142
git-rebase mainporcelain
140-
git-receive-pack synchingrepositories
143+
git-receive-pack synchelpers
141144
git-reflog ancillarymanipulators
142145
git-relink ancillarymanipulators
143-
git-repack mainporcelain
144-
git-repo-config plumbingmanipulators
145-
git-request-pull ancillaryinterrogators
146-
git-rerere mainporcelain
146+
git-repack ancillarymanipulators
147+
git-repo-config ancillarymanipulators
148+
git-request-pull foreignscminterface
149+
git-rerere ancillaryinterrogators
147150
git-reset mainporcelain
148151
git-resolve mainporcelain
149152
git-revert mainporcelain
150153
git-rev-list plumbinginterrogators
151154
git-rev-parse ancillaryinterrogators
152155
git-rm mainporcelain
153156
git-runstatus ancillaryinterrogators
154-
git-send-email ancillaryinterrogators
157+
git-send-email foreignscminterface
155158
git-send-pack synchingrepositories
156-
git-shell synchingrepositories
159+
git-shell synchelpers
157160
git-shortlog mainporcelain
158161
git-show mainporcelain
159-
git-show-branch mainporcelain
162+
git-show-branch ancillaryinterrogators
160163
git-show-index plumbinginterrogators
161164
git-show-ref plumbinginterrogators
162-
git-sh-setup ancillarymanipulators
165+
git-sh-setup purehelpers
163166
git-ssh-fetch synchingrepositories
164167
git-ssh-upload synchingrepositories
165168
git-status mainporcelain
166-
git-stripspace ancillaryinterrogators
167-
git-svn ancillarymanipulators
168-
git-svnimport ancillarymanipulators
169-
git-symbolic-ref ancillaryinterrogators
170-
git-symbolic-ref ancillarymanipulators
171-
git-tag ancillarymanipulators
169+
git-stripspace purehelpers
170+
git-svn foreignscminterface
171+
git-svnimport foreignscminterface
172+
git-symbolic-ref plumbingmanipulators
173+
git-tag mainporcelain
172174
git-tar-tree plumbinginterrogators
173175
git-unpack-file plumbinginterrogators
174176
git-unpack-objects plumbingmanipulators
175177
git-update-index plumbingmanipulators
176-
git-update-ref ancillarymanipulators
178+
git-update-ref plumbingmanipulators
177179
git-update-server-info synchingrepositories
178-
git-upload-archive synchingrepositories
179-
git-upload-pack synchingrepositories
180+
git-upload-archive synchelpers
181+
git-upload-pack synchelpers
180182
git-var plumbinginterrogators
181183
git-verify-pack plumbinginterrogators
182-
git-verify-tag mainporcelain
183-
git-whatchanged mainporcelain
184+
git-verify-tag ancillaryinterrogators
185+
git-whatchanged ancillaryinterrogators
184186
git-write-tree plumbingmanipulators

‎Documentation/git.txt‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,16 @@ Interrogators:
9393

9494
include::cmds-ancillaryinterrogators.txt[]
9595

96+
97+
Interacting with Others
98+
~~~~~~~~~~~~~~~~~~~~~~~
99+
100+
These commands are to interact with foreign SCM and with other
101+
people via patch over e-mail.
102+
103+
include::cmds-foreignscminterface.txt[]
104+
105+
96106
Low-level commands (plumbing)
97107
-----------------------------
98108

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

105-
We divide the low-level commands into commands that manipulate objects (in
115+
The interface (input, output, set of options and the semantics)
116+
to these low-level commands are meant to be a lot more stable
117+
than Porcelain level commands, because these commands are
118+
primarily for scripted use. The interface to Porcelain commands
119+
on the other hand are subject to change in order to improve the
120+
end user experience.
121+
122+
The following description divides
123+
the low-level commands into commands that manipulate objects (in
106124
the repository, index, and working tree), commands that interrogate and
107125
compare objects, and commands that move objects and references between
108126
repositories.
109127

128+
110129
Manipulation commands
111130
~~~~~~~~~~~~~~~~~~~~~
112131

@@ -127,6 +146,20 @@ Synching repositories
127146

128147
include::cmds-synchingrepositories.txt[]
129148

149+
The following are helper programs used by the above; end users
150+
typically do not use them directly.
151+
152+
include::cmds-synchelpers.txt[]
153+
154+
155+
Internal helper commands
156+
~~~~~~~~~~~~~~~~~~~~~~~~
157+
158+
These are internal helper commands used by other commands; end
159+
users typically do not use them directly.
160+
161+
include::cmds-purehelpers.txt[]
162+
130163

131164
Configuration Mechanism
132165
-----------------------

0 commit comments

Comments
 (0)