зеркало из https://github.com/microsoft/git.git
1073 строки
42 KiB
Plaintext
1073 строки
42 KiB
Plaintext
git-svn(1)
|
|
==========
|
|
|
|
NAME
|
|
----
|
|
git-svn - Bidirectional operation between a Subversion repository and Git
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'git svn' <command> [options] [arguments]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
'git svn' is a simple conduit for changesets between Subversion and Git.
|
|
It provides a bidirectional flow of changes between a Subversion and a Git
|
|
repository.
|
|
|
|
'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 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.
|
|
|
|
COMMANDS
|
|
--------
|
|
|
|
'init'::
|
|
Initializes an empty Git repository with additional
|
|
metadata directories for 'git svn'. The Subversion URL
|
|
may be specified as a command-line argument, or as full
|
|
URL arguments to -T/-t/-b. Optionally, the target
|
|
directory to operate on can be specified as a second
|
|
argument. Normally this command initializes the current
|
|
directory.
|
|
|
|
-T<trunk_subdir>;;
|
|
--trunk=<trunk_subdir>;;
|
|
-t<tags_subdir>;;
|
|
--tags=<tags_subdir>;;
|
|
-b<branches_subdir>;;
|
|
--branches=<branches_subdir>;;
|
|
-s;;
|
|
--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).
|
|
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.
|
|
--no-metadata;;
|
|
Set the 'noMetadata' option in the [svn-remote] config.
|
|
This option is not recommended, please read the 'svn.noMetadata'
|
|
section of this manpage before using this option.
|
|
--use-svm-props;;
|
|
Set the 'useSvmProps' option in the [svn-remote] config.
|
|
--use-svnsync-props;;
|
|
Set the 'useSvnsyncProps' option in the [svn-remote] config.
|
|
--rewrite-root=<URL>;;
|
|
Set the 'rewriteRoot' option in the [svn-remote] config.
|
|
--rewrite-uuid=<UUID>;;
|
|
Set the 'rewriteUUID' option in the [svn-remote] config.
|
|
--username=<user>;;
|
|
For transports that SVN handles authentication for (http,
|
|
https, and plain svn), specify the username. For other
|
|
transports (eg svn+ssh://), you must include the username in
|
|
the URL, eg svn+ssh://foo@svn.bar.com/project
|
|
--prefix=<prefix>;;
|
|
This allows one to specify a prefix which is prepended
|
|
to the names of remotes if trunk/branches/tags are
|
|
specified. The prefix does not automatically include a
|
|
trailing slash, so be sure you include one in the
|
|
argument if that is what you want. If --branches/-b is
|
|
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'.
|
|
--include-paths=<regex>;;
|
|
When passed to 'init' or 'clone' this regular expression will
|
|
be preserved as a config key. See 'fetch' for a description
|
|
of '--include-paths'.
|
|
--no-minimize-url;;
|
|
When tracking multiple directories (using --stdlayout,
|
|
--branches, or --tags options), git svn will attempt to connect
|
|
to the root (or highest allowed level) of the Subversion
|
|
repository. This default allows better tracking of history if
|
|
entire projects are moved within a repository, but may cause
|
|
issues on repositories where read access restrictions are in
|
|
place. Passing '--no-minimize-url' will allow git svn to
|
|
accept URLs as-is without attempting to connect to a higher
|
|
level directory. This option is off by default when only
|
|
one URL/branch is tracked (it would do little good).
|
|
|
|
'fetch'::
|
|
Fetch unfetched revisions from the Subversion remote we are
|
|
tracking. The name of the [svn-remote "..."] section in the
|
|
.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.
|
|
+
|
|
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.
|
|
|
|
--parent;;
|
|
Fetch only from the SVN parent of the current HEAD.
|
|
|
|
--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.
|
|
+
|
|
[verse]
|
|
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:
|
|
+
|
|
--
|
|
Skip "doc*" directory for every fetch;;
|
|
+
|
|
------------------------------------------------------------------------
|
|
--ignore-paths="^doc"
|
|
------------------------------------------------------------------------
|
|
|
|
Skip "branches" and "tags" of first level directories;;
|
|
+
|
|
------------------------------------------------------------------------
|
|
--ignore-paths="^[^/]+/(?:branches|tags)"
|
|
------------------------------------------------------------------------
|
|
--
|
|
|
|
--include-paths=<regex>;;
|
|
This allows one to specify a Perl regular expression that will
|
|
cause the inclusion of only matching paths from checkout from SVN.
|
|
The '--include-paths' option should match for every 'fetch'
|
|
(including automatic fetches due to 'clone', 'dcommit',
|
|
'rebase', etc) on a given repository. '--ignore-paths' takes
|
|
precedence over '--include-paths'.
|
|
|
|
--log-window-size=<n>;;
|
|
Fetch <n> log entries per request when scanning Subversion history.
|
|
The default is 100. For very large Subversion repositories, larger
|
|
values may be needed for 'clone'/'fetch' to complete in reasonable
|
|
time. But overly large values may lead to higher memory usage and
|
|
request timeouts.
|
|
|
|
'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' and '--parent'. 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.
|
|
|
|
--preserve-empty-dirs;;
|
|
Create a placeholder file in the local Git repository for each
|
|
empty directory fetched from Subversion. This includes directories
|
|
that become empty by removing all entries in the Subversion
|
|
repository (but not the directory itself). The placeholder files
|
|
are also tracked and removed when no longer necessary.
|
|
|
|
--placeholder-filename=<filename>;;
|
|
Set the name of placeholder files created by --preserve-empty-dirs.
|
|
Default: ".gitignore"
|
|
|
|
'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 dcommitting with 'git svn'.
|
|
+
|
|
This accepts all options that 'git svn fetch' and 'git rebase'
|
|
accept. 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.
|
|
|
|
-l;;
|
|
--local;;
|
|
Do not fetch remotely; only run 'git rebase' against the
|
|
last fetched commit from the upstream SVN.
|
|
|
|
'dcommit'::
|
|
Commit each diff from the current branch directly to the SVN
|
|
repository, and then rebase or reset (depending on whether or
|
|
not there is a diff between SVN and head). This will create
|
|
a revision in SVN for each commit in Git.
|
|
+
|
|
When an optional Git branch name (or a Git commit object name)
|
|
is specified as an argument, the subcommand works on the specified
|
|
branch, not on the current branch.
|
|
+
|
|
Use of 'dcommit' is preferred to 'set-tree' (below).
|
|
+
|
|
--no-rebase;;
|
|
After committing, do not rebase or reset.
|
|
--commit-url <URL>;;
|
|
Commit to this SVN URL (the full path). This is intended to
|
|
allow existing 'git svn' repositories created with one transport
|
|
method (e.g. `svn://` or `http://` for anonymous read) to be
|
|
reused if a user is later given access to an alternate transport
|
|
method (e.g. `svn+ssh://` or `https://`) for commit.
|
|
+
|
|
[verse]
|
|
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.
|
|
|
|
--mergeinfo=<mergeinfo>;;
|
|
Add the given merge information during the dcommit
|
|
(e.g. `--mergeinfo="/branches/foo:1-10"`). All svn server versions can
|
|
store this information (as a property), and svn clients starting from
|
|
version 1.5 can make use of it. To specify merge information from multiple
|
|
branches, use a single space character between the branches
|
|
(`--mergeinfo="/branches/foo:1-10 /branches/bar:3,5-6,8"`)
|
|
+
|
|
[verse]
|
|
config key: svn.pushmergeinfo
|
|
+
|
|
This option will cause git-svn to attempt to automatically populate the
|
|
svn:mergeinfo property in the SVN repository when possible. Currently, this can
|
|
only be done when dcommitting non-fast-forward merges where all parents but the
|
|
first have already been pushed into SVN.
|
|
|
|
--interactive;;
|
|
Ask the user to confirm that a patch set should actually be sent to SVN.
|
|
For each patch, one may answer "yes" (accept this patch), "no" (discard this
|
|
patch), "all" (accept all patches), or "quit".
|
|
+
|
|
'git svn dcommit' returns immediately if answer if "no" or "quit", without
|
|
committing anything to SVN.
|
|
|
|
'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<path>;;
|
|
--destination=<path>;;
|
|
|
|
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. <path> specifies which
|
|
path to use to create the branch or tag and should match the pattern
|
|
on the left-hand side of one of the configured branches or tags
|
|
refspecs. You can see these refspecs 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).
|
|
|
|
--username;;
|
|
Specify the SVN username to perform the commit as. This option overrides
|
|
the 'username' configuration property.
|
|
|
|
--commit-url;;
|
|
Use the specified URL to connect to the destination Subversion
|
|
repository. This is useful in cases where the source SVN
|
|
repository is read-only. This option overrides configuration
|
|
property 'commiturl'.
|
|
+
|
|
git config --get-all svn-remote.<name>.commiturl
|
|
+
|
|
|
|
--parents;;
|
|
Create parent folders. This parameter is equivalent to the parameter
|
|
--parents on svn cp commands and is useful for non-standard repository
|
|
layouts.
|
|
|
|
'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:
|
|
+
|
|
--
|
|
-r <n>[:<n>];;
|
|
--revision=<n>[:<n>];;
|
|
is supported, non-numeric args are not:
|
|
HEAD, NEXT, BASE, PREV, etc ...
|
|
-v;;
|
|
--verbose;;
|
|
it's not completely compatible with the --verbose
|
|
output in svn log, but reasonably close.
|
|
--limit=<n>;;
|
|
is NOT the same as --max-count, doesn't count
|
|
merged/excluded commits
|
|
--incremental;;
|
|
supported
|
|
--
|
|
+
|
|
New features:
|
|
+
|
|
--
|
|
--show-commit;;
|
|
shows the Git commit sha1, as well
|
|
--oneline;;
|
|
our version of --pretty=oneline
|
|
--
|
|
+
|
|
NOTE: SVN itself only stores times in UTC and nothing else. The regular svn
|
|
client converts the UTC time to the local time (or based on the TZ=
|
|
environment). This command has the same behaviour.
|
|
+
|
|
Any other arguments are passed directly to 'git log'
|
|
|
|
'blame'::
|
|
Show what revision and author last modified each line of a file. The
|
|
output of this mode is format-compatible with the output of
|
|
`svn blame' by default. Like the SVN blame command,
|
|
local uncommitted changes in the working tree are ignored;
|
|
the version of the file in the HEAD revision is annotated. Unknown
|
|
arguments are passed directly to 'git blame'.
|
|
+
|
|
--git-format;;
|
|
Produce output in the same format as 'git blame', but with
|
|
SVN revision numbers instead of Git commit hashes. In this mode,
|
|
changes that haven't been committed to SVN (including local
|
|
working-copy edits) are shown as revision 0.
|
|
|
|
'find-rev'::
|
|
When given an SVN revision number of the form 'rN', returns the
|
|
corresponding Git commit hash (this can optionally be followed by a
|
|
tree-ish to specify which branch should be searched). When given a
|
|
tree-ish, returns the corresponding SVN revision number.
|
|
+
|
|
--before;;
|
|
Don't require an exact match if given an SVN revision, instead find
|
|
the commit corresponding to the state of the SVN repository (on the
|
|
current branch) at the specified revision.
|
|
+
|
|
--after;;
|
|
Don't require an exact match if given an SVN revision; if there is
|
|
not an exact match return the closest match searching forward in the
|
|
history.
|
|
|
|
'set-tree'::
|
|
You should consider using 'dcommit' instead of this command.
|
|
Commit specified commit or tree objects to SVN. This relies on
|
|
your imported fetch data being up-to-date. This makes
|
|
absolutely no attempts to do patching when committing to SVN, it
|
|
simply overwrites files with those specified in the tree or
|
|
commit. All merging is assumed to have taken place
|
|
independently of 'git svn' functions.
|
|
|
|
'create-ignore'::
|
|
Recursively finds the svn:ignore property on directories and
|
|
creates matching .gitignore files. The resulting files are staged to
|
|
be committed, but are not committed. Use -r/--revision to refer to a
|
|
specific revision.
|
|
|
|
'show-ignore'::
|
|
Recursively finds and lists the svn:ignore property on
|
|
directories. The output is suitable for appending to
|
|
the $GIT_DIR/info/exclude file.
|
|
|
|
'mkdirs'::
|
|
Attempts to recreate empty directories that core Git cannot track
|
|
based on information in $GIT_DIR/svn/<refname>/unhandled.log files.
|
|
Empty directories are automatically recreated when using
|
|
"git svn clone" and "git svn rebase", so "mkdirs" is intended
|
|
for use after commands like "git checkout" or "git reset".
|
|
(See the svn-remote.<name>.automkdirs config file option for
|
|
more information.)
|
|
|
|
'commit-diff'::
|
|
Commits the diff of two tree-ish arguments from the
|
|
command-line. This command does not rely on being inside an `git svn
|
|
init`-ed repository. This command takes three arguments, (a) the
|
|
original tree to diff against, (b) the new tree result, (c) the
|
|
URL of the target Subversion repository. The final argument
|
|
(URL) may be omitted if you are working from a 'git svn'-aware
|
|
repository (that has been `init`-ed with 'git svn').
|
|
The -r<revision> option is required for this.
|
|
|
|
'info'::
|
|
Shows information about a file or directory similar to what
|
|
`svn info' provides. Does not currently support a -r/--revision
|
|
argument. Use the --url option to output only the value of the
|
|
'URL:' field.
|
|
|
|
'proplist'::
|
|
Lists the properties stored in the Subversion repository about a
|
|
given file or directory. Use -r/--revision to refer to a specific
|
|
Subversion revision.
|
|
|
|
'propget'::
|
|
Gets the Subversion property given as the first argument, for a
|
|
file. A specific revision can be specified with -r/--revision.
|
|
|
|
'show-externals'::
|
|
Shows the Subversion externals. Use -r/--revision to specify a
|
|
specific revision.
|
|
|
|
'gc'::
|
|
Compress $GIT_DIR/svn/<refname>/unhandled.log files in .git/svn
|
|
and remove $GIT_DIR/svn/<refname>index files in .git/svn.
|
|
|
|
'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 <n>;;
|
|
--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
|
|
-------
|
|
|
|
--shared[=(false|true|umask|group|all|world|everybody)]::
|
|
--template=<template_directory>::
|
|
Only used with the 'init' command.
|
|
These are passed directly to 'git init'.
|
|
|
|
-r <arg>::
|
|
--revision <arg>::
|
|
Used with the 'fetch' command.
|
|
+
|
|
This allows revision ranges for partial/cauterized history
|
|
to be supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges),
|
|
$NUMBER:HEAD, and BASE:$NUMBER are all supported.
|
|
+
|
|
This can allow you to make partial mirrors when running fetch;
|
|
but is generally not recommended because history will be skipped
|
|
and lost.
|
|
|
|
-::
|
|
--stdin::
|
|
Only used with the 'set-tree' command.
|
|
+
|
|
Read a list of commits from stdin and commit them in reverse
|
|
order. Only the leading sha1 is read from each line, so
|
|
'git rev-list --pretty=oneline' output can be used.
|
|
|
|
--rmdir::
|
|
Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
|
|
+
|
|
Remove directories from the SVN tree if there are no files left
|
|
behind. SVN can version empty directories, and they are not
|
|
removed by default if there are no files left in them. Git
|
|
cannot version empty directories. Enabling this flag will make
|
|
the commit to SVN act like Git.
|
|
+
|
|
[verse]
|
|
config key: svn.rmdir
|
|
|
|
-e::
|
|
--edit::
|
|
Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
|
|
+
|
|
Edit the commit message before committing to SVN. This is off by
|
|
default for objects that are commits, and forced on when committing
|
|
tree objects.
|
|
+
|
|
[verse]
|
|
config key: svn.edit
|
|
|
|
-l<num>::
|
|
--find-copies-harder::
|
|
Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
|
|
+
|
|
They are both passed directly to 'git diff-tree'; see
|
|
linkgit:git-diff-tree[1] for more information.
|
|
+
|
|
[verse]
|
|
config key: svn.l
|
|
config key: svn.findcopiesharder
|
|
|
|
-A<filename>::
|
|
--authors-file=<filename>::
|
|
Syntax is compatible with the file used by 'git cvsimport':
|
|
+
|
|
------------------------------------------------------------------------
|
|
loginname = Joe User <user@example.com>
|
|
------------------------------------------------------------------------
|
|
+
|
|
If this option is specified and 'git svn' encounters an SVN
|
|
committer name that does not exist in the authors-file, 'git svn'
|
|
will abort operation. The user will then have to add the
|
|
appropriate entry. Re-running the previous 'git svn' command
|
|
after the authors-file is modified should continue operation.
|
|
+
|
|
[verse]
|
|
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. Specify a second time to make it
|
|
even less verbose.
|
|
|
|
--repack[=<n>]::
|
|
--repack-flags=<flags>::
|
|
These should help keep disk usage sane for large fetches with
|
|
many revisions.
|
|
+
|
|
--repack takes an optional argument for the number of revisions
|
|
to fetch before repacking. This defaults to repacking every
|
|
1000 commits fetched if no argument is specified.
|
|
+
|
|
--repack-flags are passed directly to 'git repack'.
|
|
+
|
|
[verse]
|
|
config key: svn.repack
|
|
config key: svn.repackflags
|
|
|
|
-m::
|
|
--merge::
|
|
-s<strategy>::
|
|
--strategy=<strategy>::
|
|
-p::
|
|
--preserve-merges::
|
|
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').
|
|
|
|
-n::
|
|
--dry-run::
|
|
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.
|
|
+
|
|
For 'rebase', display the local branch associated with the upstream 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.
|
|
|
|
--use-log-author::
|
|
When retrieving svn commits into Git (as part of 'fetch', 'rebase', or
|
|
'dcommit' operations), look for the first `From:` or `Signed-off-by:` line
|
|
in the log message and use that as the author string.
|
|
--add-author-from::
|
|
When committing to svn from Git (as part of 'commit-diff', 'set-tree' or 'dcommit'
|
|
operations), if the existing log message doesn't already have a
|
|
`From:` or `Signed-off-by:` line, append a `From:` line based on the
|
|
Git commit's author string. If you use this, then `--use-log-author`
|
|
will retrieve a valid author string for all commits.
|
|
|
|
|
|
ADVANCED OPTIONS
|
|
----------------
|
|
|
|
-i<GIT_SVN_ID>::
|
|
--id <GIT_SVN_ID>::
|
|
This sets GIT_SVN_ID (instead of using the environment). This
|
|
allows the user to override the default refname to fetch from
|
|
when tracking a single URL. The 'log' and 'dcommit' commands
|
|
no longer require this switch as an argument.
|
|
|
|
-R<remote name>::
|
|
--svn-remote <remote name>::
|
|
Specify the [svn-remote "<remote name>"] section to use,
|
|
this allows SVN multiple repositories to be tracked.
|
|
Default: "svn"
|
|
|
|
--follow-parent::
|
|
This option is only relevant if we are tracking branches (using
|
|
one of the repository layout options --trunk, --tags,
|
|
--branches, --stdlayout). For each tracked branch, try to find
|
|
out where its revision was copied from, and set
|
|
a suitable parent in the first Git commit for the branch.
|
|
This is especially helpful when we're tracking a directory
|
|
that has been moved around within the repository. If this
|
|
feature is disabled, the branches created by 'git svn' will all
|
|
be linear and not share any history, meaning that there will be
|
|
no information on where branches were branched off or merged.
|
|
However, following long/convoluted histories can take a long
|
|
time, so disabling this feature may speed up the cloning
|
|
process. This feature is enabled by default, use
|
|
--no-follow-parent to disable it.
|
|
+
|
|
[verse]
|
|
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.
|
|
+
|
|
This option can only be used for one-shot imports as 'git svn'
|
|
will not be able to fetch again without metadata. Additionally,
|
|
if you lose your .git/svn/**/.rev_map.* files, 'git svn' will not
|
|
be able to rebuild them.
|
|
+
|
|
The 'git svn log' command will not work on repositories using
|
|
this, either. Using this conflicts with the 'useSvmProps'
|
|
option for (hopefully) obvious reasons.
|
|
+
|
|
This option is NOT recommended as it makes it difficult to track down
|
|
old references to SVN revision numbers in existing documentation, bug
|
|
reports and archives. If you plan to eventually migrate from SVN to Git
|
|
and are certain about dropping SVN history, consider
|
|
linkgit:git-filter-branch[1] instead. filter-branch also allows
|
|
reformatting of metadata for ease-of-reading and rewriting authorship
|
|
info for non-"svn.authorsFile" users.
|
|
|
|
svn.useSvmProps::
|
|
svn-remote.<name>.useSvmProps::
|
|
This allows 'git svn' to re-map repository URLs and UUIDs from
|
|
mirrors created using SVN::Mirror (or svk) for metadata.
|
|
+
|
|
If an SVN revision has a property, "svm:headrev", it is likely
|
|
that the revision was created by SVN::Mirror (also used by SVK).
|
|
The property contains a repository UUID and a revision. We want
|
|
to make it look like we are mirroring the original URL, so
|
|
introduce a helper function that returns the original identity
|
|
URL and UUID, and use it when generating metadata in commit
|
|
messages.
|
|
|
|
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.
|
|
|
|
svn-remote.<name>.rewriteUUID::
|
|
Similar to the useSvmProps option; this is for users who need
|
|
to remap the UUID manually. This may be useful in situations
|
|
where the original UUID is not available via either useSvmProps
|
|
or useSvnsyncProps.
|
|
|
|
svn-remote.<name>.pushurl::
|
|
|
|
Similar to Git's 'remote.<name>.pushurl', this key is designed
|
|
to be used in cases where 'url' points to an SVN repository
|
|
via a read-only transport, to provide an alternate read/write
|
|
transport. It is assumed that both keys point to the same
|
|
repository. Unlike 'commiturl', 'pushurl' is a base path. If
|
|
either 'commiturl' or 'pushurl' could be used, 'commiturl'
|
|
takes precedence.
|
|
|
|
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".
|
|
|
|
svn.pathnameencoding::
|
|
This instructs git svn to recode pathnames to a given encoding.
|
|
It can be used by windows users and by those who work in non-utf8
|
|
locales to avoid corrupted file names with non-ASCII characters.
|
|
Valid encodings are the ones supported by Perl's Encode module.
|
|
|
|
svn-remote.<name>.automkdirs::
|
|
Normally, the "git svn clone" and "git svn rebase" commands
|
|
attempt to recreate empty directories that are in the
|
|
Subversion repository. If this option is set to "false", then
|
|
empty directories will only be created if the "git svn mkdirs"
|
|
command is run explicitly. If unset, 'git svn' assumes this
|
|
option to be "true".
|
|
|
|
Since the noMetadata, rewriteRoot, rewriteUUID, 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 options can be used per svn-remote
|
|
section because they affect the 'git-svn-id:' metadata line, except
|
|
for rewriteRoot and rewriteUUID which can be used together.
|
|
|
|
|
|
BASIC EXAMPLES
|
|
--------------
|
|
|
|
Tracking and contributing to the trunk of a Subversion-managed project
|
|
(ignoring tags and branches):
|
|
|
|
------------------------------------------------------------------------
|
|
# Clone a repo (like git clone):
|
|
git svn clone http://svn.example.com/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
|
|
# Append svn:ignore settings to the default Git exclude file:
|
|
git svn show-ignore >> .git/info/exclude
|
|
------------------------------------------------------------------------
|
|
|
|
Tracking and contributing to an entire Subversion-managed project
|
|
(complete with a trunk, tags and branches):
|
|
|
|
------------------------------------------------------------------------
|
|
# Clone a repo with standard SVN directory layout (like git clone):
|
|
git svn clone http://svn.example.com/project --stdlayout
|
|
# Or, if the repo uses a non-standard directory layout:
|
|
git svn clone http://svn.example.com/project -T tr -b branch -t tag
|
|
# 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 may only dcommit to one branch/tag/trunk at a time. The usage
|
|
# of dcommit/rebase/show-ignore should be the same as above.
|
|
------------------------------------------------------------------------
|
|
|
|
The initial 'git svn clone' can be quite time-consuming
|
|
(especially for large Subversion repositories). If multiple
|
|
people (or one person with multiple machines) want to use
|
|
'git svn' to interact with the same Subversion repository, you can
|
|
do the initial 'git svn clone' to a repository on a server and
|
|
have each person clone that repository with 'git clone':
|
|
|
|
------------------------------------------------------------------------
|
|
# Do the initial import on a server
|
|
ssh server "cd /pub && git svn clone http://svn.example.com/project
|
|
# Clone locally - make sure the refs/remotes/ space matches the server
|
|
mkdir project
|
|
cd project
|
|
git init
|
|
git remote add origin server:/pub/project
|
|
git config --replace-all remote.origin.fetch '+refs/remotes/*:refs/remotes/*'
|
|
git fetch
|
|
# Prevent fetch/pull from remote Git server in the future,
|
|
# we only want to use git svn for future updates
|
|
git config --remove-section remote.origin
|
|
# Create a local branch from one of the branches just fetched
|
|
git checkout -b master FETCH_HEAD
|
|
# Initialize 'git svn' locally (be sure to use the same URL and -T/-b/-t options as were used on server)
|
|
git svn init http://svn.example.com/project
|
|
# Pull the latest changes from Subversion
|
|
git svn rebase
|
|
------------------------------------------------------------------------
|
|
|
|
REBASE VS. PULL/MERGE
|
|
---------------------
|
|
Prefer to use 'git svn rebase' or 'git rebase', rather than
|
|
'git pull' or 'git merge' to synchronize unintegrated commits with a 'git svn'
|
|
branch. Doing so will keep the history of unintegrated commits linear with
|
|
respect to the upstream SVN repository and allow the use of the preferred
|
|
'git svn dcommit' subcommand to push unintegrated commits back into SVN.
|
|
|
|
Originally, 'git svn' recommended that developers pulled or merged from
|
|
the 'git svn' branch. This was because the author favored
|
|
`git svn set-tree B` to commit a single head rather than the
|
|
`git svn set-tree A..B` notation to commit multiple commits. Use of
|
|
'git pull' or 'git merge' with `git svn set-tree A..B` will cause non-linear
|
|
history to be flattened when committing into SVN and this can lead to merge
|
|
commits unexpectedly reversing previous commits in SVN.
|
|
|
|
MERGE TRACKING
|
|
--------------
|
|
While 'git svn' can track
|
|
copy history (including branches and tags) for repositories adopting a
|
|
standard layout, it cannot yet represent merge history that happened
|
|
inside git back upstream to SVN users. Therefore it is advised that
|
|
users keep history as linear as possible inside Git to ease
|
|
compatibility with SVN (see the CAVEATS section below).
|
|
|
|
HANDLING OF SVN BRANCHES
|
|
------------------------
|
|
If 'git svn' is configured to fetch branches (and --follow-branches
|
|
is in effect), it sometimes creates multiple Git branches for one
|
|
SVN branch, where the additional branches have names of the form
|
|
'branchname@nnn' (with nnn an SVN revision number). These additional
|
|
branches are created if 'git svn' cannot find a parent commit for the
|
|
first commit in an SVN branch, to connect the branch to the history of
|
|
the other branches.
|
|
|
|
Normally, the first commit in an SVN branch consists
|
|
of a copy operation. 'git svn' will read this commit to get the SVN
|
|
revision the branch was created from. It will then try to find the
|
|
Git commit that corresponds to this SVN revision, and use that as the
|
|
parent of the branch. However, it is possible that there is no suitable
|
|
Git commit to serve as parent. This will happen, among other reasons,
|
|
if the SVN branch is a copy of a revision that was not fetched by 'git
|
|
svn' (e.g. because it is an old revision that was skipped with
|
|
'--revision'), or if in SVN a directory was copied that is not tracked
|
|
by 'git svn' (such as a branch that is not tracked at all, or a
|
|
subdirectory of a tracked branch). In these cases, 'git svn' will still
|
|
create a Git branch, but instead of using an existing Git commit as the
|
|
parent of the branch, it will read the SVN history of the directory the
|
|
branch was copied from and create appropriate Git commits. This is
|
|
indicated by the message "Initializing parent: <branchname>".
|
|
|
|
Additionally, it will create a special branch named
|
|
'<branchname>@<SVN-Revision>', where <SVN-Revision> is the SVN revision
|
|
number the branch was copied from. This branch will point to the newly
|
|
created parent commit of the branch. If in SVN the branch was deleted
|
|
and later recreated from a different version, there will be multiple
|
|
such branches with an '@'.
|
|
|
|
Note that this may mean that multiple Git commits are created for a
|
|
single SVN revision.
|
|
|
|
An example: in an SVN repository with a standard
|
|
trunk/tags/branches layout, a directory trunk/sub is created in r.100.
|
|
In r.200, trunk/sub is branched by copying it to branches/. 'git svn
|
|
clone -s' will then create a branch 'sub'. It will also create new Git
|
|
commits for r.100 through r.199 and use these as the history of branch
|
|
'sub'. Thus there will be two Git commits for each revision from r.100
|
|
to r.199 (one containing trunk/, one containing trunk/sub/). Finally,
|
|
it will create a branch 'sub@200' pointing to the new parent commit of
|
|
branch 'sub' (i.e. the commit for r.200 and trunk/sub/).
|
|
|
|
CAVEATS
|
|
-------
|
|
|
|
For the sake of simplicity and interoperating with Subversion,
|
|
it is recommended that all 'git svn' users clone, fetch and dcommit
|
|
directly from the SVN server, and avoid all 'git clone'/'pull'/'merge'/'push'
|
|
operations between Git repositories and branches. The recommended
|
|
method of exchanging code between Git branches and users is
|
|
'git format-patch' and 'git am', or just 'dcommit'ing to the SVN repository.
|
|
|
|
Running 'git merge' or 'git pull' is NOT recommended on a branch you
|
|
plan to 'dcommit' from because Subversion users cannot see any
|
|
merges you've made. Furthermore, if you merge or pull from a Git branch
|
|
that is a mirror of an SVN branch, 'dcommit' may commit to the wrong
|
|
branch.
|
|
|
|
If you do merge, note the following rule: 'git svn dcommit' will
|
|
attempt to commit on top of the SVN commit named in
|
|
------------------------------------------------------------------------
|
|
git log --grep=^git-svn-id: --first-parent -1
|
|
------------------------------------------------------------------------
|
|
You 'must' therefore ensure that the most recent commit of the branch
|
|
you want to dcommit to is the 'first' parent of the merge. Chaos will
|
|
ensue otherwise, especially if the first parent is an older commit on
|
|
the same SVN branch.
|
|
|
|
'git clone' does not clone branches under the refs/remotes/ hierarchy or
|
|
any 'git svn' metadata, or config. So repositories created and managed with
|
|
using 'git svn' should use 'rsync' for cloning, if cloning is to be done
|
|
at all.
|
|
|
|
Since 'dcommit' uses rebase internally, any Git branches you 'git push' to
|
|
before 'dcommit' on will require forcing an overwrite of the existing ref
|
|
on the remote repository. This is generally considered bad practice,
|
|
see the linkgit:git-push[1] documentation for details.
|
|
|
|
Do not use the --amend option of linkgit:git-commit[1] on a change you've
|
|
already dcommitted. It is considered bad practice to --amend commits
|
|
you've already pushed to a remote repository for other users, and
|
|
dcommit with SVN is analogous to that.
|
|
|
|
When cloning an SVN repository, if none of the options for describing
|
|
the repository layout is used (--trunk, --tags, --branches,
|
|
--stdlayout), 'git svn clone' will create a Git repository with
|
|
completely linear history, where branches and tags appear as separate
|
|
directories in the working copy. While this is the easiest way to get a
|
|
copy of a complete repository, for projects with many branches it will
|
|
lead to a working copy many times larger than just the trunk. Thus for
|
|
projects using the standard directory structure (trunk/branches/tags),
|
|
it is recommended to clone with option '--stdlayout'. If the project
|
|
uses a non-standard structure, and/or if branches and tags are not
|
|
required, it is easiest to only clone one directory (typically trunk),
|
|
without giving any repository layout options. If the full history with
|
|
branches and tags is required, the options '--trunk' / '--branches' /
|
|
'--tags' must be used.
|
|
|
|
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
|
|
----
|
|
|
|
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). Committing
|
|
renamed and copied files is fully supported if they're similar enough
|
|
for Git to detect them.
|
|
|
|
In SVN, it is possible (though discouraged) to commit changes to a tag
|
|
(because a tag is just a directory copy, thus technically the same as a
|
|
branch). When cloning an SVN repository, 'git svn' cannot know if such a
|
|
commit to a tag will happen in the future. Thus it acts conservatively
|
|
and imports all SVN tags as branches, prefixing the tag name with 'tags/'.
|
|
|
|
CONFIGURATION
|
|
-------------
|
|
|
|
'git svn' stores [svn-remote] configuration information in the
|
|
repository .git/config file. It is similar the core Git
|
|
[remote] sections except 'fetch' keys do not accept glob
|
|
arguments; but they are instead handled by the 'branches'
|
|
and 'tags' keys. Since some SVN repositories are oddly
|
|
configured with multiple projects glob expansions such those
|
|
listed below are allowed:
|
|
|
|
------------------------------------------------------------------------
|
|
[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/*
|
|
------------------------------------------------------------------------
|
|
|
|
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 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'.
|
|
|
|
It is also possible to fetch a subset of branches or tags by using a
|
|
comma-separated list of names within braces. For example:
|
|
|
|
------------------------------------------------------------------------
|
|
[svn-remote "huge-project"]
|
|
url = http://server.org/svn
|
|
fetch = trunk/src:refs/remotes/trunk
|
|
branches = branches/{red,green}/src:refs/remotes/branches/*
|
|
tags = tags/{1.0,2.0}/src:refs/remotes/tags/*
|
|
------------------------------------------------------------------------
|
|
|
|
Multiple fetch, branches, and tags keys are supported:
|
|
|
|
------------------------------------------------------------------------
|
|
[svn-remote "messy-repo"]
|
|
url = http://server.org/svn
|
|
fetch = trunk/project-a:refs/remotes/project-a/trunk
|
|
fetch = branches/demos/june-project-a-demo:refs/remotes/project-a/demos/june-demo
|
|
branches = branches/server/*:refs/remotes/project-a/branches/*
|
|
branches = branches/demos/2011/*:refs/remotes/project-a/2011-demos/*
|
|
tags = tags/server/*:refs/remotes/project-a/tags/*
|
|
------------------------------------------------------------------------
|
|
|
|
Creating a branch in such a configuration requires disambiguating which
|
|
location to use using the -d or --destination flag:
|
|
|
|
------------------------------------------------------------------------
|
|
$ git svn branch -d branches/server release-2-3-0
|
|
------------------------------------------------------------------------
|
|
|
|
Note that git-svn keeps track of the highest revision in which a branch
|
|
or tag has appeared. If the subset of branches or tags is changed after
|
|
fetching, then .git/svn/.metadata must be manually edited to remove (or
|
|
reset) branches-maxRev and/or tags-maxRev as appropriate.
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkgit:git-rebase[1]
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[1] suite
|