man page: add an EXAMPLES section.
Avery Pennarun committed
May 30, 2009 at 14:24 UTC
dd07906252a3983fdec396ea6c58de12548713e1
1 file changed
+62
git-subtree.txt
+62
@@ -223,6 +223,68 @@ OPTIONS FOR split
223
subproject's history to be part of your project anyway.
224
225
226
+EXAMPLES
227
+--------
228
+Let's use the repository for the git source code as an example.
229
+First, get your own copy of the git.git repository:
230
+
231
+ $ git clone git://git.kernel.org/pub/scm/git/git.git test-git
232
+ $ cd test-git
233
+
234
+gitweb (commit 1130ef3) was merged into git as of commit
235
+0a8f4f0, after which it was no longer maintained separately.
236
+But imagine it had been maintained separately, and we wanted to
237
+extract git's changes to gitweb since that time, to share with
238
+the upstream. You could do this:
239
+
240
+ $ git subtree split --prefix=gitweb --annotate='(split) ' \
241
+ 0a8f4f0^.. --onto=1130ef3 --rejoin \
242
+ --branch gitweb-latest
243
+ $ gitk gitweb-latest
244
+ $ git push git@github.com:whatever/gitweb gitweb-latest:master
245
+
246
+(We use '0a8f4f0^..' because that means "all the changes from
247
+0a8f4f0 to the current version, including 0a8f4f0 itself.")
248
+
249
+If gitweb had originally been merged using 'git subtree add' (or
250
+a previous split had already been done with --rejoin specified)
251
+then you can do all your splits without having to remember any
252
+weird commit ids:
253
+
254
+ $ git subtree split --prefix=gitweb --annotate='(split) ' --rejoin \
255
+ --branch gitweb-latest2
256
+
257
+And you can merge changes back in from the upstream project just
258
+as easily:
259
+
260
+ $ git subtree pull --prefix=gitweb \
261
+ git@github.com:whatever/gitweb gitweb-latest:master
262
+
263
+Or, using '--squash', you can actually rewind to an earlier
264
+version of gitweb:
265
+
266
+ $ git subtree merge --prefix=gitweb --squash gitweb-latest~10
267
+
268
+Then make some changes:
269
+
270
+ $ date >gitweb/myfile
271
+ $ git add gitweb/myfile
272
+ $ git commit -m 'created myfile'
273
+
274
+And fast forward again:
275
+
276
+ $ git subtree merge --prefix=gitweb --squash gitweb-latest
277
+
278
+And notice that your change is still intact:
279
+
280
+ $ ls -l gitweb/myfile
281
+
282
+And you can split it out and look at your changes versus
283
+the standard gitweb:
284
+
285
+ git log gitweb-latest..$(git subtree split --prefix=gitweb)
286
+
287
+
288
AUTHOR
289
------
290
Written by Avery Pennarun <apenwarr@gmail.com>