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>
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index ba3f7ce..bd163cf 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -65,6 +65,32 @@
.git/config file may be specified as an optional command-line
argument.
+'clone'::
+ Runs 'init' and 'fetch'. It will automatically create a
+ directory based on the basename of the URL passed to it;
+ or if a second argument is passed; it will create a directory
+ and work within that. It accepts all arguments that the
+ 'init' and 'fetch' commands accept; with the exception of
+ '--fetch-all'. After a repository is cloned, the 'fetch'
+ command will be able to update revisions without affecting
+ the working tree; and the 'rebase' command will be able
+ to update the working tree with the latest changes.
+
+'rebase'::
+ This fetches revisions from the SVN parent of the current HEAD
+ and rebases the current (uncommitted to SVN) work against it.
+
+ This works similarly to 'svn update' or 'git-pull' except that
+ it preserves linear history with 'git-rebase' instead of
+ 'git-merge' for ease of dcommit-ing with git-svn.
+
+ This accepts all options that 'git-svn fetch' and 'git-rebase'
+ accepts. However '--fetch-all' only fetches from the current
+ [svn-remote], and not all [svn-remote] definitions.
+
+ Like 'git-rebase'; this requires that the working tree be clean
+ and have no uncommitted changes.
+
'dcommit'::
Commit each diff from a specified head directly to the SVN
repository, and then rebase or reset (depending on whether or
@@ -234,7 +260,7 @@
-s<strategy>::
--strategy=<strategy>::
-These are only used with the 'dcommit' command.
+These are only used with the 'dcommit' and 'rebase' commands.
Passed directly to git-rebase when using 'dcommit' if a
'git-reset' cannot be used (see dcommit).
@@ -276,6 +302,11 @@
config key: svn.followparent
+--
+CONFIG FILE-ONLY OPTIONS
+------------------------
+--
+
svn.noMetadata:
svn-remote.<name>.noMetadata:
This gets rid of the git-svn-id: lines at the end of every commit.
@@ -301,8 +332,27 @@
URL and UUID, and use it when generating metadata in commit
messages.
- Using this conflicts with the 'noMetadata' option for
- (hopefully) obvious reasons.
+svn.useSvnsyncProps:
+svn-remote.<name>.useSvnsyncprops:
+ Similar to the useSvmProps option; this is for users
+ of the svnsync(1) command distributed with SVN 1.4.x and
+ later.
+
+svn-remote.<name>.rewriteRoot
+ This allows users to create repositories from alternate
+ URLs. For example, an administrator could run git-svn on the
+ server locally (accessing via file://) but wish to distribute
+ the repository with a public http:// or svn:// URL in the
+ metadata so users of it will see the public URL.
+
+
+Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps
+options all affect the metadata generated and used by git-svn; they
+*must* be set in the configuration file before any history is imported
+and these settings should never be changed once they are set.
+
+Additionally, only one of these four options can be used per-svn-remote
+section because they affect the 'git-svn-id:' metadata line.
--
@@ -312,17 +362,20 @@
Tracking and contributing to a the trunk of a Subversion-managed project:
------------------------------------------------------------------------
-# Initialize a repo (like git init):
- git-svn init http://svn.foo.org/project/trunk
-# Fetch remote revisions:
- git-svn fetch
-# Create your own branch to hack on:
- git checkout -b my-branch remotes/git-svn
-# Do some work, and then commit your new changes to SVN, as well as
-# automatically updating your working HEAD:
+# Clone a repo (like git clone):
+ git-svn clone http://svn.foo.org/project/trunk
+# Enter the newly cloned directory:
+ cd trunk
+# You should be on master branch, double-check with git-branch
+ git branch
+# Do some work and commit locally to git:
+ git commit ...
+# Something is committed to SVN, rebase your local changes against the
+# latest changes in SVN:
+ git-svn rebase
+# Now commit your changes (that were committed previously using git) to SVN,
+# as well as automatically updating your working HEAD:
git-svn dcommit
-# Something is committed to SVN, rebase the latest into your branch:
- git-svn fetch && git rebase remotes/git-svn
# Append svn:ignore settings to the default git exclude file:
git-svn show-ignore >> .git/info/exclude
------------------------------------------------------------------------
@@ -331,19 +384,15 @@
(complete with a trunk, tags and branches):
------------------------------------------------------------------------
-# Initialize a repo (like git init):
- git-svn init http://svn.foo.org/project -T trunk -b branches -t tags
-# Fetch remote revisions:
- git-svn fetch
-# Create your own branch of trunk to hack on:
- git checkout -b my-trunk remotes/trunk
-# Do some work, and then commit your new changes to SVN, as well as
-# automatically updating your working HEAD:
- git-svn dcommit
-# Something has been committed to trunk, rebase the latest into your branch:
- git-svn fetch && git rebase remotes/trunk
-# Append svn:ignore settings of trunk to the default git exclude file:
- git-svn show-ignore -i trunk >> .git/info/exclude
+# Clone a repo (like git clone):
+ git-svn clone http://svn.foo.org/project -T trunk -b branches -t tags
+# View all branches and tags you have cloned:
+ git branch -r
+# Reset your master to trunk (or any other branch, replacing 'trunk'
+# with the appropriate name):
+ git reset --hard remotes/trunk
+# You may only dcommit to one branch/tag/trunk at a time. The usage
+# of dcommit/rebase/show-ignore should be teh same as above.
------------------------------------------------------------------------
REBASE VS. PULL/MERGE
@@ -356,7 +405,7 @@
If you use 'git-svn set-tree A..B' to commit several diffs and you do
not have the latest remotes/git-svn merged into my-branch, you should
-use 'git rebase' to update your work branch instead of 'git pull' or
+use 'git-svn rebase' to update your work branch instead of 'git pull' or
'git merge'. 'pull/merge' can cause non-linear history to be flattened
when committing into SVN, which can lead to merge commits reversing
previous commits in SVN.
@@ -373,17 +422,15 @@
BUGS
----
-We ignore all SVN properties except svn:executable. Too difficult to
-map them since we rely heavily on git write-tree being _exactly_ the
-same on both the SVN and git working trees and I prefer not to clutter
-working trees with metadata files.
+We ignore all SVN properties except svn:executable. Any unhandled
+properties are logged to $GIT_DIR/svn/<refname>/unhandled.log
Renamed and copied directories are not detected by git and hence not
tracked when committing to SVN. I do not plan on adding support for
this as it's quite difficult and time-consuming to get working for all
-the possible corner cases (git doesn't do it, either). Renamed and
-copied files are fully supported if they're similar enough for git to
-detect them.
+the possible corner cases (git doesn't do it, either). Committing
+renamed and copied files are fully supported if they're similar enough
+for git to detect them.
CONFIGURATION
-------------
