git-svn: documentation updates
This documents the 'clone' and 'rebase' commands of git-svn. Additionaly, examples are updated to use them instead of the lower-level 'init' and 'fetch' commands. Signed-off-by: Eric Wong <normalperson@yhbt.net>
Eric Wong committed
Feb 18, 2007 at 02:10 UTC
a81ed0b63edb0d473e17e078de2269b735156a79
1 file changed
+81
-34
Documentation/git-svn.txt
+81
-34
@@ -65,6 +65,32 @@ COMMANDS
65
.git/config file may be specified as an optional command-line
66
argument.
67
68
+'clone'::
69
+ Runs 'init' and 'fetch'. It will automatically create a
70
+ directory based on the basename of the URL passed to it;
71
+ or if a second argument is passed; it will create a directory
72
+ and work within that. It accepts all arguments that the
73
+ 'init' and 'fetch' commands accept; with the exception of
74
+ '--fetch-all'. After a repository is cloned, the 'fetch'
75
+ command will be able to update revisions without affecting
76
+ the working tree; and the 'rebase' command will be able
77
+ to update the working tree with the latest changes.
78
+
79
+'rebase'::
80
+ This fetches revisions from the SVN parent of the current HEAD
81
+ and rebases the current (uncommitted to SVN) work against it.
82
+
83
+ This works similarly to 'svn update' or 'git-pull' except that
84
+ it preserves linear history with 'git-rebase' instead of
85
+ 'git-merge' for ease of dcommit-ing with git-svn.
86
+
87
+ This accepts all options that 'git-svn fetch' and 'git-rebase'
88
+ accepts. However '--fetch-all' only fetches from the current
89
+ [svn-remote], and not all [svn-remote] definitions.
90
+
91
+ Like 'git-rebase'; this requires that the working tree be clean
92
+ and have no uncommitted changes.
93
+
94
'dcommit'::
95
Commit each diff from a specified head directly to the SVN
96
repository, and then rebase or reset (depending on whether or
@@ -234,7 +260,7 @@ config key: svn.repackflags
260
-s<strategy>::
261
--strategy=<strategy>::
262
237
-These are only used with the 'dcommit' command.
263
+These are only used with the 'dcommit' and 'rebase' commands.
264
265
Passed directly to git-rebase when using 'dcommit' if a
266
'git-reset' cannot be used (see dcommit).
@@ -276,6 +302,11 @@ no longer require this switch as an argument.
302
303
config key: svn.followparent
304
305
+--
306
+CONFIG FILE-ONLY OPTIONS
307
+------------------------
308
+--
309
+
310
svn.noMetadata:
311
svn-remote.<name>.noMetadata:
312
This gets rid of the git-svn-id: lines at the end of every commit.
@@ -301,8 +332,27 @@ svn-remote.<name>.useSvmProps:
332
URL and UUID, and use it when generating metadata in commit
333
messages.
334
304
- Using this conflicts with the 'noMetadata' option for
305
- (hopefully) obvious reasons.
335
+svn.useSvnsyncProps:
336
+svn-remote.<name>.useSvnsyncprops:
337
+ Similar to the useSvmProps option; this is for users
338
+ of the svnsync(1) command distributed with SVN 1.4.x and
339
+ later.
340
+
341
+svn-remote.<name>.rewriteRoot
342
+ This allows users to create repositories from alternate
343
+ URLs. For example, an administrator could run git-svn on the
344
+ server locally (accessing via file://) but wish to distribute
345
+ the repository with a public http:// or svn:// URL in the
346
+ metadata so users of it will see the public URL.
347
+
348
+
349
+Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps
350
+options all affect the metadata generated and used by git-svn; they
351
+*must* be set in the configuration file before any history is imported
352
+and these settings should never be changed once they are set.
353
+
354
+Additionally, only one of these four options can be used per-svn-remote
355
+section because they affect the 'git-svn-id:' metadata line.
356
357
--
358
@@ -312,17 +362,20 @@ Basic Examples
362
Tracking and contributing to a the trunk of a Subversion-managed project:
363
364
------------------------------------------------------------------------
315
-# Initialize a repo (like git init):
316
- git-svn init http://svn.foo.org/project/trunk
317
-# Fetch remote revisions:
318
- git-svn fetch
319
-# Create your own branch to hack on:
320
- git checkout -b my-branch remotes/git-svn
321
-# Do some work, and then commit your new changes to SVN, as well as
322
-# automatically updating your working HEAD:
365
+# Clone a repo (like git clone):
366
+ git-svn clone http://svn.foo.org/project/trunk
367
+# Enter the newly cloned directory:
368
+ cd trunk
369
+# You should be on master branch, double-check with git-branch
370
+ git branch
371
+# Do some work and commit locally to git:
372
+ git commit ...
373
+# Something is committed to SVN, rebase your local changes against the
374
+# latest changes in SVN:
375
+ git-svn rebase
376
+# Now commit your changes (that were committed previously using git) to SVN,
377
+# as well as automatically updating your working HEAD:
378
git-svn dcommit
324
-# Something is committed to SVN, rebase the latest into your branch:
325
- git-svn fetch && git rebase remotes/git-svn
379
# Append svn:ignore settings to the default git exclude file:
380
git-svn show-ignore >> .git/info/exclude
381
------------------------------------------------------------------------
@@ -331,19 +384,15 @@ Tracking and contributing to an entire Subversion-managed project
384
(complete with a trunk, tags and branches):
385
386
------------------------------------------------------------------------
334
-# Initialize a repo (like git init):
335
- git-svn init http://svn.foo.org/project -T trunk -b branches -t tags
336
-# Fetch remote revisions:
337
- git-svn fetch
338
-# Create your own branch of trunk to hack on:
339
- git checkout -b my-trunk remotes/trunk
340
-# Do some work, and then commit your new changes to SVN, as well as
341
-# automatically updating your working HEAD:
342
- git-svn dcommit
343
-# Something has been committed to trunk, rebase the latest into your branch:
344
- git-svn fetch && git rebase remotes/trunk
345
-# Append svn:ignore settings of trunk to the default git exclude file:
346
- git-svn show-ignore -i trunk >> .git/info/exclude
387
+# Clone a repo (like git clone):
388
+ git-svn clone http://svn.foo.org/project -T trunk -b branches -t tags
389
+# View all branches and tags you have cloned:
390
+ git branch -r
391
+# Reset your master to trunk (or any other branch, replacing 'trunk'
392
+# with the appropriate name):
393
+ git reset --hard remotes/trunk
394
+# You may only dcommit to one branch/tag/trunk at a time. The usage
395
+# of dcommit/rebase/show-ignore should be teh same as above.
396
------------------------------------------------------------------------
397
398
REBASE VS. PULL/MERGE
@@ -356,7 +405,7 @@ pulled or merged from. This is because the author favored
405
406
If you use 'git-svn set-tree A..B' to commit several diffs and you do
407
not have the latest remotes/git-svn merged into my-branch, you should
359
-use 'git rebase' to update your work branch instead of 'git pull' or
408
+use 'git-svn rebase' to update your work branch instead of 'git pull' or
409
'git merge'. 'pull/merge' can cause non-linear history to be flattened
410
when committing into SVN, which can lead to merge commits reversing
411
previous commits in SVN.
@@ -373,17 +422,15 @@ how 'svn log' works).
422
BUGS
423
----
424
376
-We ignore all SVN properties except svn:executable. Too difficult to
377
-map them since we rely heavily on git write-tree being _exactly_ the
378
-same on both the SVN and git working trees and I prefer not to clutter
379
-working trees with metadata files.
425
+We ignore all SVN properties except svn:executable. Any unhandled
426
+properties are logged to $GIT_DIR/svn/<refname>/unhandled.log
427
428
Renamed and copied directories are not detected by git and hence not
429
tracked when committing to SVN. I do not plan on adding support for
430
this as it's quite difficult and time-consuming to get working for all
384
-the possible corner cases (git doesn't do it, either). Renamed and
385
-copied files are fully supported if they're similar enough for git to
386
-detect them.
431
+the possible corner cases (git doesn't do it, either). Committing
432
+renamed and copied files are fully supported if they're similar enough
433
+for git to detect them.
434
435
CONFIGURATION
436
-------------