DESCRIPTION
-----------
git-svn is a simple conduit for changesets between Subversion and git.
-It is not to be confused with gitlink:git-svnimport[1], which is
+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
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>::
+-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)
-
---no-metadata::
+ (--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::
+--use-svm-props;;
Set the 'useSvmProps' option in the [svn-remote] config.
---use-svnsync-props::
+--use-svnsync-props;;
Set the 'useSvnsyncProps' option in the [svn-remote] config.
---rewrite-root=<URL>::
+--rewrite-root=<URL>;;
Set the 'rewriteRoot' option in the [svn-remote] config.
---username=<USER>::
+--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 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.
+--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>::
+--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. This is useful if
- you wish to track multiple projects that share a common
- repository.
+ 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
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.
+'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
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
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'::
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 copy 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.
+
'set-tree'::
You should consider using 'dcommit' instead of this command.
Commit specified commit or tree objects to SVN. This relies on
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
+ specfic revision.
+
'show-ignore'::
Recursively finds and lists the svn:ignore property on
directories. The output is suitable for appending to
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.
+
--
OPTIONS
--shared[={false|true|umask|group|all|world|everybody}]::
--template=<template_directory>::
Only used with the 'init' command.
- These are passed directly to gitlink:git-init[1].
+ These are passed directly to linkgit:git-init[1].
-r <ARG>::
--revision <ARG>::
Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
They are both passed directly to git-diff-tree see
-gitlink:git-diff-tree[1] for more information.
+linkgit:git-diff-tree[1] for more information.
[verse]
config key: svn.l
to fetch before repacking. This defaults to repacking every
1000 commits fetched if no argument is specified.
---repack-flags are passed directly to gitlink:git-repack[1].
+--repack-flags are passed directly to linkgit:git-repack[1].
[verse]
config key: svn.repack
BASIC EXAMPLES
--------------
-Tracking and contributing to a the trunk of a Subversion-managed project:
+Tracking and contributing to the trunk of a Subversion-managed project:
------------------------------------------------------------------------
# Clone a repo (like git clone):
# 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
---------------------
DESIGN PHILOSOPHY
-----------------
Merge tracking in Subversion is lacking and doing branched development
-with Subversion is cumbersome as a result. git-svn does not do
-automated merge/branch tracking by default and leaves it entirely up to
-the user on the git side. git-svn does however follow copy
-history of the directory that it is tracking, however (much like
-how 'svn log' works).
+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
----
------------------------------------------------------------------------
Keep in mind that the '*' (asterisk) wildcard of the local ref
-(left of the ':') *must* be the farthest right path component;
+(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 componet (surrounded by '/' or EOL). This
+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
-gitlink:git-config[1]
+linkgit:git-config[1]
SEE ALSO
--------
-gitlink:git-rebase[1]
+linkgit:git-rebase[1]
Author
------