@matheusbsbs / matheus-bagliano / commits / a81ed0b63e
Fork 0

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 -------------