![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
index a35b9de3bfde036391b0ac869bf927361d3d4c67..340f1be02a21495182584b0c09512a8608c1a61a 100644 (file)
DESCRIPTION
-----------
git-svn is a simple conduit for changesets between Subversion and git.
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
read-only.
git-svn was originally designed for an individual developer who wants a
argument. Normally this command initializes the current
directory.
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
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.
Set the 'noMetadata' option in the [svn-remote] config.
---use-svm-props::
+--use-svm-props;;
Set the 'useSvmProps' option in the [svn-remote] config.
Set the 'useSvmProps' option in the [svn-remote] config.
---use-svnsync-props::
+--use-svnsync-props;;
Set the 'useSvnsyncProps' option in the [svn-remote] config.
Set the 'useSvnsyncProps' option in the [svn-remote] config.
---rewrite-root=<URL>::
+--rewrite-root=<URL>;;
Set the 'rewriteRoot' option in the [svn-remote] config.
Set the 'rewriteRoot' option in the [svn-remote] config.
---username=<USER>::
+--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
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
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'::
-
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
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
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
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.
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.
-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
'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.
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'::
--
'log'::
+
Any other arguments are passed directly to `git log'
+
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
--
'find-rev'::
When given an SVN revision number of the form 'rN', returns the
- corresponding git commit hash. When given a tree-ish, returns the
- corresponding SVN revision number.
+ 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.
'set-tree'::
You should consider using 'dcommit' instead of this command.
repository (that has been init-ed with git-svn).
The -r<revision> option is required for this.
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
--
OPTIONS
--shared[={false|true|umask|group|all|world|everybody}]::
--template=<template_directory>::
Only used with the 'init' command.
--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>::
-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
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
[verse]
config key: svn.l
to fetch before repacking. This defaults to repacking every
1000 commits fetched if no argument is specified.
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
[verse]
config key: svn.repack
BASIC EXAMPLES
--------------
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):
------------------------------------------------------------------------
# Clone a repo (like git clone):
# of dcommit/rebase/show-ignore should be the same as above.
------------------------------------------------------------------------
# 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
---------------------
REBASE VS. PULL/MERGE
---------------------
DESIGN PHILOSOPHY
-----------------
Merge tracking in Subversion is lacking and doing branched development
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
----
BUGS
----
------------------------------------------------------------------------
Keep in mind that the '*' (asterisk) wildcard of the local ref
------------------------------------------------------------------------
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
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
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
--------
SEE ALSO
--------
-gitlink:git-rebase[1]
+linkgit:git-rebase[1]
Author
------
Author
------