Documentation: improve "add", "pull" and "format-patch" examples
Before this patch in "git-add.txt" and "git-format-patch.txt", the commands used in the examples were "git-CMD" instead of "git CMD". This patch fixes that. In "git-pull.txt" only the last example had the code sample in an asciidoc "Listing Block", and in the other two files, none. This patch fixes that by putting all code samples in listing blocks. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Christian Couder committed
May 7, 2008 at 06:29 UTC
921177f50fe107a5807baf7e2f63177a86945a60
3 files changed
+108
-69
Documentation/git-add.txt
+15
-9
@@ -98,21 +98,27 @@ those in info/exclude. See link:repository-layout.html[repository layout].
98
99
EXAMPLES
100
--------
101
-git-add Documentation/\\*.txt::
101
103
- Adds content from all `\*.txt` files under `Documentation`
104
- directory and its subdirectories.
102
+* Adds content from all `\*.txt` files under `Documentation` directory
103
+and its subdirectories:
104
++
105
+------------
106
+$ git add Documentation/\\*.txt
107
+------------
108
+
109
Note that the asterisk `\*` is quoted from the shell in this
110
example; this lets the command to include the files from
111
subdirectories of `Documentation/` directory.
112
110
-git-add git-*.sh::
111
-
112
- Considers adding content from all git-*.sh scripts.
113
- Because this example lets shell expand the asterisk
114
- (i.e. you are listing the files explicitly), it does not
115
- consider `subdir/git-foo.sh`.
113
+* Considers adding content from all git-*.sh scripts:
114
++
115
+------------
116
+$ git add git-*.sh
117
+------------
118
++
119
+Because this example lets shell expand the asterisk (i.e. you are
120
+listing the files explicitly), it does not consider
121
+`subdir/git-foo.sh`.
122
123
Interactive mode
124
----------------
Documentation/git-format-patch.txt
+41
-26
@@ -174,32 +174,47 @@ and file suffix, and number patches when outputting more than one.
174
EXAMPLES
175
--------
176
177
-git-format-patch -k --stdout R1..R2 | git-am -3 -k::
178
- Extract commits between revisions R1 and R2, and apply
179
- them on top of the current branch using `git-am` to
180
- cherry-pick them.
181
-
182
-git-format-patch origin::
183
- Extract all commits which are in the current branch but
184
- not in the origin branch. For each commit a separate file
185
- is created in the current directory.
186
-
187
-git-format-patch \--root origin::
188
- Extract all commits that lead to 'origin' since the
189
- inception of the project.
190
-
191
-git-format-patch -M -B origin::
192
- The same as the previous one. Additionally, it detects
193
- and handles renames and complete rewrites intelligently to
194
- produce a renaming patch. A renaming patch reduces the
195
- amount of text output, and generally makes it easier to
196
- review it. Note that the "patch" program does not
197
- understand renaming patches, so use it only when you know
198
- the recipient uses git to apply your patch.
199
-
200
-git-format-patch -3::
201
- Extract three topmost commits from the current branch
202
- and format them as e-mailable patches.
177
+* Extract commits between revisions R1 and R2, and apply them on top of
178
+the current branch using `git-am` to cherry-pick them:
179
++
180
+------------
181
+$ git format-patch -k --stdout R1..R2 | git-am -3 -k
182
+------------
183
+
184
+* Extract all commits which are in the current branch but not in the
185
+origin branch:
186
++
187
+------------
188
+$ git format-patch origin
189
+------------
190
++
191
+For each commit a separate file is created in the current directory.
192
+
193
+* Extract all commits that lead to 'origin' since the inception of the
194
+project:
195
++
196
+------------
197
+$ git format-patch \--root origin
198
+------------
199
+
200
+* The same as the previous one:
201
++
202
+------------
203
+$ git format-patch -M -B origin
204
+------------
205
++
206
+Additionally, it detects and handles renames and complete rewrites
207
+intelligently to produce a renaming patch. A renaming patch reduces
208
+the amount of text output, and generally makes it easier to review it.
209
+Note that the "patch" program does not understand renaming patches, so
210
+use it only when you know the recipient uses git to apply your patch.
211
+
212
+* Extract three topmost commits from the current branch and format them
213
+as e-mailable patches:
214
++
215
+------------
216
+$ git format-patch -3
217
+------------
218
219
See Also
220
--------
Documentation/git-pull.txt
+52
-34
@@ -111,40 +111,58 @@ rules apply:
111
EXAMPLES
112
--------
113
114
-git pull, git pull origin::
115
- Update the remote-tracking branches for the repository
116
- you cloned from, then merge one of them into your
117
- current branch. Normally the branch merged in is
118
- the HEAD of the remote repository, but the choice is
119
- determined by the branch.<name>.remote and
120
- branch.<name>.merge options; see linkgit:git-config[1]
121
- for details.
122
-
123
-git pull origin next::
124
- Merge into the current branch the remote branch `next`;
125
- leaves a copy of `next` temporarily in FETCH_HEAD, but
126
- does not update any remote-tracking branches.
127
-
128
-git pull . fixes enhancements::
129
- Bundle local branch `fixes` and `enhancements` on top of
130
- the current branch, making an Octopus merge. This `git pull .`
131
- syntax is equivalent to `git merge`.
132
-
133
-git pull -s ours . obsolete::
134
- Merge local branch `obsolete` into the current branch,
135
- using `ours` merge strategy.
136
-
137
-git pull --no-commit . maint::
138
- Merge local branch `maint` into the current branch, but
139
- do not make a commit automatically. This can be used
140
- when you want to include further changes to the merge,
141
- or want to write your own merge commit message.
114
+* Update the remote-tracking branches for the repository
115
+ you cloned from, then merge one of them into your
116
+ current branch:
117
++
118
+------------------------------------------------
119
+$ git pull, git pull origin
120
+------------------------------------------------
121
++
122
+Normally the branch merged in is the HEAD of the remote repository,
123
+but the choice is determined by the branch.<name>.remote and
124
+branch.<name>.merge options; see linkgit:git-config[1] for details.
125
+
126
+* Merge into the current branch the remote branch `next`:
127
++
128
+------------------------------------------------
129
+$ git pull origin next
130
+------------------------------------------------
131
++
132
+This leaves a copy of `next` temporarily in FETCH_HEAD, but
133
+does not update any remote-tracking branches.
134
+
135
+* Bundle local branch `fixes` and `enhancements` on top of
136
+ the current branch, making an Octopus merge:
137
++
138
+------------------------------------------------
139
+$ git pull . fixes enhancements
140
+------------------------------------------------
141
++
142
+This `git pull .` syntax is equivalent to `git merge`.
143
+
144
+* Merge local branch `obsolete` into the current branch, using `ours`
145
+ merge strategy:
146
++
147
+------------------------------------------------
148
+$ git pull -s ours . obsolete
149
+------------------------------------------------
150
+
151
+* Merge local branch `maint` into the current branch, but do not make
152
+ a commit automatically:
153
++
154
+------------------------------------------------
155
+$ git pull --no-commit . maint
156
+------------------------------------------------
157
++
158
+This can be used when you want to include further changes to the
159
+merge, or want to write your own merge commit message.
160
+
161
You should refrain from abusing this option to sneak substantial
162
changes into a merge commit. Small fixups like bumping
163
release/version name would be acceptable.
164
147
-Command line pull of multiple branches from one repository::
165
+* Command line pull of multiple branches from one repository:
166
+
167
------------------------------------------------
168
$ git checkout master
@@ -152,12 +170,12 @@ $ git fetch origin +pu:pu maint:tmp
170
$ git pull . tmp
171
------------------------------------------------
172
+
155
-This updates (or creates, as necessary) branches `pu` and `tmp`
156
-in the local repository by fetching from the branches
157
-(respectively) `pu` and `maint` from the remote repository.
173
+This updates (or creates, as necessary) branches `pu` and `tmp` in
174
+the local repository by fetching from the branches (respectively)
175
+`pu` and `maint` from the remote repository.
176
+
159
-The `pu` branch will be updated even if it is does not
160
-fast-forward; the others will not be.
177
+The `pu` branch will be updated even if it is does not fast-forward;
178
+the others will not be.
179
+
180
The final command then merges the newly fetched `tmp` into master.
181