зеркало из https://github.com/microsoft/git.git
587 строки
20 KiB
Plaintext
587 строки
20 KiB
Plaintext
git-svn(1)
|
|
==========
|
|
|
|
NAME
|
|
----
|
|
git-svn - Bidirectional operation between a single Subversion branch and git
|
|
|
|
SYNOPSIS
|
|
--------
|
|
'git-svn' <command> [options] [arguments]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
git-svn is a simple conduit for changesets between Subversion and git.
|
|
It is not to be confused with linkgit:git-svnimport[1], which is
|
|
read-only.
|
|
|
|
git-svn was originally designed for an individual developer who wants a
|
|
bidirectional flow of changesets between a single branch in Subversion
|
|
and an arbitrary number of branches in git. Since its inception,
|
|
git-svn has gained the ability to track multiple branches in a manner
|
|
similar to git-svnimport.
|
|
|
|
git-svn is especially useful when it comes to tracking repositories
|
|
not organized in the way Subversion developers recommend (trunk,
|
|
branches, tags directories).
|
|
|
|
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). 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.
|
|
--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.
|
|
--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.
|
|
|
|
'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.
|
|
|
|
'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 dcommiting 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.
|
|
|
|
-l;;
|
|
--local;;
|
|
Do not fetch remotely; only run 'git-rebase' against the
|
|
last fetched commit from the upstream SVN.
|
|
|
|
'dcommit'::
|
|
Commit each diff from a specified head 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.
|
|
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.
|
|
This is advantageous over 'set-tree' (below) because it produces
|
|
cleaner, more linear history.
|
|
+
|
|
--no-rebase;;
|
|
After committing, do not rebase or reset.
|
|
--
|
|
|
|
'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>];;
|
|
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
|
|
--
|
|
+
|
|
Any other arguments are passed directly to `git log'
|
|
|
|
'blame'::
|
|
Show what revision and author last modified each line of a file. This is
|
|
identical to `git blame', but SVN revision numbers are shown instead of git
|
|
commit hashes.
|
|
+
|
|
All arguments are passed directly to `git blame'.
|
|
|
|
--
|
|
'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.
|
|
|
|
'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.
|
|
|
|
'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.
|
|
|
|
'commit-diff'::
|
|
Commits the diff of two tree-ish arguments from the
|
|
command-line. This command is intended for interoperability with
|
|
git-svnimport and 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.
|
|
|
|
--
|
|
|
|
OPTIONS
|
|
-------
|
|
--
|
|
|
|
--shared[={false|true|umask|group|all|world|everybody}]::
|
|
--template=<template_directory>::
|
|
Only used with the 'init' command.
|
|
These are passed directly to linkgit:git-init[1].
|
|
|
|
-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.
|
|
|
|
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.
|
|
|
|
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 files used by git-svnimport and
|
|
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.
|
|
|
|
config key: svn.authorsfile
|
|
|
|
-q::
|
|
--quiet::
|
|
Make git-svn 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 linkgit:git-repack[1].
|
|
|
|
[verse]
|
|
config key: svn.repack
|
|
config key: svn.repackflags
|
|
|
|
-m::
|
|
--merge::
|
|
-s<strategy>::
|
|
--strategy=<strategy>::
|
|
|
|
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 is only used with the 'dcommit' command.
|
|
|
|
Print out the series of git arguments that would show
|
|
which diffs would be committed to SVN.
|
|
|
|
--
|
|
|
|
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 is especially helpful when we're tracking a directory
|
|
that has been moved around within the repository, or if we
|
|
started tracking a branch and never tracked the trunk it was
|
|
descended from. This feature is enabled by default, use
|
|
--no-follow-parent to disable it.
|
|
|
|
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.
|
|
|
|
If you lose your .git/svn/git-svn/.rev_db file, git-svn will not
|
|
be able to rebuild it and you won't be able to fetch again,
|
|
either. This is fine for one-shot imports.
|
|
|
|
The 'git-svn log' command will not work on repositories using
|
|
this, either. Using this conflicts with the 'useSvmProps'
|
|
option for (hopefully) obvious reasons.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
--
|
|
|
|
BASIC EXAMPLES
|
|
--------------
|
|
|
|
Tracking and contributing to the trunk of a Subversion-managed project:
|
|
|
|
------------------------------------------------------------------------
|
|
# 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
|
|
# 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 (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 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.foo.org/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 --add remote.origin.fetch=+refs/remotes/*:refs/remotes/*
|
|
git fetch
|
|
# 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.foo.org/project
|
|
# Pull the latest changes from Subversion
|
|
git-svn rebase
|
|
------------------------------------------------------------------------
|
|
|
|
REBASE VS. PULL/MERGE
|
|
---------------------
|
|
|
|
Originally, git-svn recommended that the remotes/git-svn branch be
|
|
pulled or merged from. This is 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.
|
|
|
|
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-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.
|
|
|
|
DESIGN PHILOSOPHY
|
|
-----------------
|
|
Merge tracking in Subversion is lacking and doing branched development
|
|
with Subversion can be cumbersome as a result. 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).
|
|
|
|
CAVEATS
|
|
-------
|
|
|
|
For the sake of simplicity and interoperating with a less-capable system
|
|
(SVN), 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 dcommiting to the SVN repository.
|
|
|
|
Running 'git-merge' or 'git-pull' is NOT recommended on a branch you
|
|
plan to dcommit from. Subversion does not represent merges in any
|
|
reasonable or useful fashion; so users using Subversion 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.
|
|
|
|
'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(1) 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 git-push(1) documentation for details.
|
|
|
|
Do not use the --amend option of 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.
|
|
|
|
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 are fully supported if they're similar enough
|
|
for git to detect them.
|
|
|
|
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
|
|
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
|
|
(right of the ':') *must* be the farthest right path component;
|
|
however the remote wildcard may be anywhere as long as it's own
|
|
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
|
|
linkgit:git-config[1]
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkgit:git-rebase[1]
|
|
|
|
Author
|
|
------
|
|
Written by Eric Wong <normalperson@yhbt.net>.
|
|
|
|
Documentation
|
|
-------------
|
|
Written by Eric Wong <normalperson@yhbt.net>.
|