NAME
----
-git-svn - Bidirectional operation between a single Subversion branch and git
+git-svn - Bidirectional operation between a Subversion repository and git
SYNOPSIS
--------
It provides a bidirectional flow of changes between a Subversion and a git
repository.
-'git-svn' can track a single Subversion branch simply by using a
-URL to the branch, follow branches laid out in the Subversion recommended
-method (trunk, branches, tags directories) with the --stdlayout option, or
-follow branches in any layout with the -T/-t/-b options (see options to
-'init' below, and also the 'clone' command).
+'git-svn' can track a standard Subversion repository,
+following the common "trunk/branches/tags" layout, with the --stdlayout option.
+It can also follow branches and tags in any layout with the -T/-t/-b options
+(see options to 'init' below, and also the 'clone' command).
-Once tracking a Subversion branch (with any of the above methods), the git
+Once tracking a Subversion repository (with any of the above methods), the git
repository can be updated from Subversion by the 'fetch' command and
Subversion updated from git by the 'dcommit' command.
--stdlayout;;
These are optional command-line options for init. Each of
these flags can point to a relative repository path
- (--tags=project/tags') or a full url
- (--tags=https://foo.org/project/tags). The option --stdlayout is
+ (--tags=project/tags) or a full url
+ (--tags=https://foo.org/project/tags).
+ You can specify more than one --tags and/or --branches options, in case
+ your Subversion repository places tags or branches under multiple paths.
+ The option --stdlayout is
a shorthand way of setting trunk,tags,branches as the relative paths,
which is the Subversion default. If any of the other options are given
as well, they take precedence.
specified, the prefix must include a trailing slash.
Setting a prefix is useful if you wish to track multiple
projects that share a common repository.
+--ignore-paths=<regex>;;
+ When passed to 'init' or 'clone' this regular expression will
+ be preserved as a config key. See 'fetch' for a description
+ of '--ignore-paths'.
'fetch'::
Fetch unfetched revisions from the Subversion remote we are
.git/config file may be specified as an optional command-line
argument.
+--localtime;;
+ Store Git commit times in the local timezone instead of UTC. This
+ makes 'git-log' (even without --date=local) show the same times
+ that `svn log` would in the local timezone.
+
+--parent;;
+ Fetch only from the SVN parent of the current HEAD.
+
+This doesn't interfere with interoperating with the Subversion
+repository you cloned from, but if you wish for your local Git
+repository to be able to interoperate with someone else's local Git
+repository, either don't use this option or you should both use it in
+the same local timezone.
+
+--ignore-paths=<regex>;;
+ This allows one to specify a Perl regular expression that will
+ cause skipping of all matching paths from checkout from SVN.
+ The '--ignore-paths' option should match for every 'fetch'
+ (including automatic fetches due to 'clone', 'dcommit',
+ 'rebase', etc) on a given repository.
+
+config key: svn-remote.<name>.ignore-paths
+
+ If the ignore-paths config key is set and the command
+ line option is also given, both regular expressions
+ will be used.
+
+Examples:
+
+ --ignore-paths="^doc" - skip "doc*" directory for every
+ fetch.
+
+ --ignore-paths="^[^/]+/(?:branches|tags)" - skip
+ "branches" and "tags" of first level directories.
+
'clone'::
Runs 'init' and 'fetch'. It will automatically create a
directory based on the basename of the URL passed to it;
It is recommended that you run 'git-svn' fetch and rebase (not
pull or merge) your commits against the latest changes in the
SVN repository.
- An optional command-line argument may be specified as an
- alternative to HEAD.
+ An optional revision or branch argument may be specified, and
+ causes 'git-svn' to do all work on that revision/branch
+ instead of HEAD.
This is advantageous over 'set-tree' (below) because it produces
cleaner, more linear history.
+
reused if a user is later given access to an alternate transport
method (e.g. `svn+ssh://` or `https://`) for commit.
+config key: svn-remote.<name>.commiturl
+
+config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options)
+
Using this option for any other purpose (don't ask)
is very strongly discouraged.
--
+'branch'::
+ Create a branch in the SVN repository.
+
+-m;;
+--message;;
+ Allows to specify the commit message.
+
+-t;;
+--tag;;
+ Create a tag by using the tags_subdir instead of the branches_subdir
+ specified during git svn init.
+
+-d;;
+--destination;;
+ If more than one --branches (or --tags) option was given to the 'init'
+ or 'clone' command, you must provide the location of the branch (or
+ tag) you wish to create in the SVN repository. The value of this
+ option must match one of the paths specified by a --branches (or
+ --tags) option. You can see these paths with the commands
++
+ git config --get-all svn-remote.<name>.branches
+ git config --get-all svn-remote.<name>.tags
++
+where <name> is the name of the SVN repository as specified by the -R option to
+'init' (or "svn" by default).
+
+'tag'::
+ Create a tag in the SVN repository. This is a shorthand for
+ 'branch -t'.
+
'log'::
This should make it easy to look up svn log messages when svn
users refer to -r/--revision numbers.
The following features from `svn log' are supported:
+
--
---revision=<n>[:<n>];;
+-r/--revision=<n>[:<n>];;
is supported, non-numeric args are not:
HEAD, NEXT, BASE, PREV, etc ...
-v/--verbose;;
Shows the Subversion externals. Use -r/--revision to specify a
specific revision.
+'reset'::
+ Undoes the effects of 'fetch' back to the specified revision.
+ This allows you to re-'fetch' an SVN revision. Normally the
+ contents of an SVN revision should never change and 'reset'
+ should not be necessary. However, if SVN permissions change,
+ or if you alter your --ignore-paths option, a 'fetch' may fail
+ with "not found in commit" (file not previously visible) or
+ "checksum mismatch" (missed a modification). If the problem
+ file cannot be ignored forever (with --ignore-paths) the only
+ way to repair the repo is to use 'reset'.
+
+Only the rev_map and refs/remotes/git-svn are changed. Follow 'reset'
+with a 'fetch' and then 'git-reset' or 'git-rebase' to move local
+branches onto the new tree.
+
+-r/--revision=<n>;;
+ Specify the most recent revision to keep. All later revisions
+ are discarded.
+-p/--parent;;
+ Discard the specified revision as well, keeping the nearest
+ parent instead.
+Example:;;
+Assume you have local changes in "master", but you need to refetch "r2".
+
+------------
+ r1---r2---r3 remotes/git-svn
+ \
+ A---B master
+------------
+
+Fix the ignore-paths or SVN permissions problem that caused "r2" to
+be incomplete in the first place. Then:
+
+[verse]
+git svn reset -r2 -p
+git svn fetch
+
+------------
+ r1---r2'--r3' remotes/git-svn
+ \
+ r2---r3---A---B master
+------------
+
+Then fixup "master" with 'git-rebase'.
+Do NOT use 'git-merge' or your history will not be compatible with a
+future 'dcommit'!
+
+[verse]
+git rebase --onto remotes/git-svn A^ master
+
+------------
+ r1---r2'--r3' remotes/git-svn
+ \
+ A'--B' master
+------------
+
+
--
OPTIONS
config key: svn.authorsfile
+--authors-prog=<filename>::
+
+If this option is specified, for each SVN committer name that does not
+exist in the authors file, the given file is executed with the committer
+name as the first argument. The program is expected to return a single
+line of the form "Name <email>", which will be treated as if included in
+the authors file.
+
-q::
--quiet::
- Make 'git-svn' less verbose.
+ Make 'git-svn' less verbose. Specify a second time to make it
+ even less verbose.
--repack[=<n>]::
--repack-flags=<flags>::
-n::
--dry-run::
-This can be used with the 'dcommit' and 'rebase' commands.
+This can be used with the 'dcommit', 'rebase', 'branch' and 'tag'
+commands.
For 'dcommit', print out the series of git arguments that would show
which diffs would be committed to SVN.
repository associated with the current branch and the URL of svn
repository that will be fetched from.
+For 'branch' and 'tag', display the urls that will be used for copying when
+creating the branch or tag.
+
--
ADVANCED OPTIONS
the repository with a public http:// or svn:// URL in the
metadata so users of it will see the public URL.
+svn.brokenSymlinkWorkaround::
+This disables potentially expensive checks to workaround broken symlinks
+checked into SVN by broken clients. Set this option to "false" if you
+track a SVN repository with many empty blobs that are not symlinks.
+This option may be changed while "git-svn" is running and take effect on
+the next revision fetched. If unset, git-svn assumes this option to be
+"true".
+
--
Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps
git svn clone http://svn.example.com/project -T trunk -b branches -t tags
# View all branches and tags you have cloned:
git branch -r
+# Create a new branch in SVN
+ git svn branch waldo
# Reset your master to trunk (or any other branch, replacing 'trunk'
# with the appropriate name):
git reset --hard remotes/trunk
you've already pushed to a remote repository for other users, and
dcommit with SVN is analogous to that.
+When using multiple --branches or --tags, 'git-svn' does not automatically
+handle name collisions (for example, if two branches from different paths have
+the same name, or if a branch and a tag have the same name). In these cases,
+use 'init' to set up your git repository then, before your first 'fetch', edit
+the .git/config file so that the branches and tags are associated with
+different name spaces. For example:
+
+ branches = stable/*:refs/remotes/svn/stable/*
+ branches = debug/*:refs/remotes/svn/debug/*
+
BUGS
----
------------------------------------------------------------------------
[svn-remote "project-a"]
url = http://server.org/svn
+ fetch = trunk/project-a:refs/remotes/project-a/trunk
branches = branches/*/project-a:refs/remotes/project-a/branches/*
tags = tags/*/project-a:refs/remotes/project-a/tags/*
- trunk = trunk/project-a:refs/remotes/project-a/trunk
------------------------------------------------------------------------
-Keep in mind that the '*' (asterisk) wildcard of the local ref
+Keep in mind that the '\*' (asterisk) wildcard of the local ref
(right of the ':') *must* be the farthest right path component;
-however the remote wildcard may be anywhere as long as it's own
+however the remote wildcard may be anywhere as long as it's an
independent path component (surrounded by '/' or EOL). This
type of configuration is not automatically created by 'init' and
should be manually entered with a text-editor or using 'git-config'.