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>
Junio C Hamano committed
Jan 18, 2007 at 22:32 UTC
89bf207758530fd151895680f7236ce626feea9c
3 files changed
+86
-48
Documentation/Makefile
+4
-1
@@ -76,7 +76,10 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
76
cmds-mainporcelain.txt \
77
cmds-plumbinginterrogators.txt \
78
cmds-plumbingmanipulators.txt \
79
- cmds-synchingrepositories.txt
79
+ cmds-synchingrepositories.txt \
80
+ cmds-synchelpers.txt \
81
+ cmds-purehelpers.txt \
82
+ cmds-foreignscminterface.txt
83
84
$(cmds_txt): cmd-list.perl $(MAN1_TXT)
85
perl ./cmd-list.perl
Documentation/cmd-list.perl
+48
-46
@@ -45,7 +45,10 @@ for my $cat (qw(ancillaryinterrogators
45
mainporcelain
46
plumbinginterrogators
47
plumbingmanipulators
48
- synchingrepositories)) {
48
+ synchingrepositories
49
+ foreignscminterface
50
+ purehelpers
51
+ synchelpers)) {
52
my $out = "cmds-$cat.txt";
53
open O, '>', "$out+" or die "Cannot open output file $out+";
54
for (@{$cmds{$cat}}) {
@@ -59,10 +62,10 @@ __DATA__
62
git-add mainporcelain
63
git-am mainporcelain
64
git-annotate ancillaryinterrogators
62
-git-applymbox mainporcelain
63
-git-applypatch ancillarymanipulators
65
+git-applymbox ancillaryinterrogators
66
+git-applypatch purehelpers
67
git-apply plumbingmanipulators
65
-git-archimport ancillarymanipulators
68
+git-archimport foreignscminterface
69
git-archive mainporcelain
70
git-bisect mainporcelain
71
git-blame ancillaryinterrogators
@@ -70,7 +73,7 @@ git-branch mainporcelain
73
git-cat-file plumbinginterrogators
74
git-checkout-index plumbingmanipulators
75
git-checkout mainporcelain
73
-git-check-ref-format ancillaryinterrogators
76
+git-check-ref-format purehelpers
77
git-cherry ancillaryinterrogators
78
git-cherry-pick mainporcelain
79
git-clean mainporcelain
@@ -79,11 +82,11 @@ git-commit mainporcelain
82
git-commit-tree plumbingmanipulators
83
git-convert-objects ancillarymanipulators
84
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
90
git-diff-files plumbinginterrogators
91
git-diff-index plumbinginterrogators
92
git-diff mainporcelain
@@ -91,34 +94,34 @@ git-diff-stages plumbinginterrogators
94
git-diff-tree plumbinginterrogators
95
git-fetch mainporcelain
96
git-fetch-pack synchingrepositories
94
-git-fmt-merge-msg ancillaryinterrogators
97
+git-fmt-merge-msg purehelpers
98
git-for-each-ref plumbinginterrogators
99
git-format-patch mainporcelain
97
-git-fsck-objects plumbinginterrogators
98
-git-gc ancillarymanipulators
100
+git-fsck-objects ancillaryinterrogators
101
+git-gc mainporcelain
102
git-get-tar-commit-id ancillaryinterrogators
103
git-grep mainporcelain
104
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
108
git-index-pack plumbingmanipulators
106
-git-init plumbingmanipulators
109
+git-init mainporcelain
110
git-instaweb ancillaryinterrogators
111
gitk mainporcelain
112
git-local-fetch synchingrepositories
113
git-log mainporcelain
114
git-lost-found ancillarymanipulators
115
git-ls-files plumbinginterrogators
113
-git-ls-remote mainporcelain
116
+git-ls-remote plumbinginterrogators
117
git-ls-tree plumbinginterrogators
115
-git-mailinfo ancillaryinterrogators
116
-git-mailsplit ancillaryinterrogators
118
+git-mailinfo purehelpers
119
+git-mailsplit purehelpers
120
git-merge-base plumbinginterrogators
121
git-merge-file plumbingmanipulators
122
git-merge-index plumbingmanipulators
123
git-merge mainporcelain
121
-git-merge-one-file ancillarymanipulators
124
+git-merge-one-file purehelpers
125
git-merge-tree ancillaryinterrogators
126
git-mktag plumbingmanipulators
127
git-mktree plumbingmanipulators
@@ -126,24 +129,24 @@ git-mv mainporcelain
129
git-name-rev plumbinginterrogators
130
git-pack-objects plumbingmanipulators
131
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
136
git-prune ancillarymanipulators
137
git-prune-packed plumbingmanipulators
138
git-pull mainporcelain
139
git-push mainporcelain
137
-git-quiltimport ancillarymanipulators
140
+git-quiltimport foreignscminterface
141
git-read-tree plumbingmanipulators
142
git-rebase mainporcelain
140
-git-receive-pack synchingrepositories
143
+git-receive-pack synchelpers
144
git-reflog ancillarymanipulators
145
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
150
git-reset mainporcelain
151
git-resolve mainporcelain
152
git-revert mainporcelain
@@ -151,34 +154,33 @@ git-rev-list plumbinginterrogators
154
git-rev-parse ancillaryinterrogators
155
git-rm mainporcelain
156
git-runstatus ancillaryinterrogators
154
-git-send-email ancillaryinterrogators
157
+git-send-email foreignscminterface
158
git-send-pack synchingrepositories
156
-git-shell synchingrepositories
159
+git-shell synchelpers
160
git-shortlog mainporcelain
161
git-show mainporcelain
159
-git-show-branch mainporcelain
162
+git-show-branch ancillaryinterrogators
163
git-show-index plumbinginterrogators
164
git-show-ref plumbinginterrogators
162
-git-sh-setup ancillarymanipulators
165
+git-sh-setup purehelpers
166
git-ssh-fetch synchingrepositories
167
git-ssh-upload synchingrepositories
168
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
174
git-tar-tree plumbinginterrogators
175
git-unpack-file plumbinginterrogators
176
git-unpack-objects plumbingmanipulators
177
git-update-index plumbingmanipulators
176
-git-update-ref ancillarymanipulators
178
+git-update-ref plumbingmanipulators
179
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
182
git-var plumbinginterrogators
183
git-verify-pack plumbinginterrogators
182
-git-verify-tag mainporcelain
183
-git-whatchanged mainporcelain
184
+git-verify-tag ancillaryinterrogators
185
+git-whatchanged ancillaryinterrogators
186
git-write-tree plumbingmanipulators
Documentation/git.txt
+34
-1
@@ -93,6 +93,16 @@ Interrogators:
93
94
include::cmds-ancillaryinterrogators.txt[]
95
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
+
106
Low-level commands (plumbing)
107
-----------------------------
108
@@ -102,11 +112,20 @@ development of alternative porcelains. Developers of such porcelains
112
might start by reading about gitlink:git-update-index[1] and
113
gitlink:git-read-tree[1].
114
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
124
the repository, index, and working tree), commands that interrogate and
125
compare objects, and commands that move objects and references between
126
repositories.
127
128
+
129
Manipulation commands
130
~~~~~~~~~~~~~~~~~~~~~
131
@@ -127,6 +146,20 @@ Synching repositories
146
147
include::cmds-synchingrepositories.txt[]
148
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
+
163
164
Configuration Mechanism
165
-----------------------