contrib/git-svn/git-svn.txt

   1 git-svn(1)
   2 ==========
   3
   4 NAME
   5 ----
   6 git-svn - bidirectional operation between a single Subversion branch and git
   7
   8 SYNOPSIS
   9 --------
  10 'git-svn' <command> [options] [arguments]
  11
  12 DESCRIPTION
  13 -----------
  14 git-svn is a simple conduit for changesets between a single Subversion
  15 branch and git.
  16
  17 git-svn is not to be confused with git-svnimport.  The were designed
  18 with very different goals in mind.
  19
  20 git-svn is designed for an individual developer who wants a
  21 bidirectional flow of changesets between a single branch in Subversion
  22 and an arbitrary number of branches in git.  git-svnimport is designed
  23 for read-only operation on repositories that match a particular layout
  24 (albeit the recommended one by SVN developers).
  25
  26 For importing svn, git-svnimport is potentially more powerful when
  27 operating on repositories organized under the recommended
  28 trunk/branch/tags structure, and should be faster, too.
  29
  30 git-svn mostly ignores the very limited view of branching that
  31 Subversion has.  This allows git-svn to be much easier to use,
  32 especially on repositories that are not organized in a manner that
  33 git-svnimport is designed for.
  34
  35 COMMANDS
  36 --------
  37 init::
  38         Creates an empty git repository with additional metadata
  39         directories for git-svn.  The Subversion URL must be specified
  40         as a command-line argument.
  41
  42 fetch::
  43         Fetch unfetched revisions from the Subversion URL we are
  44         tracking.  refs/remotes/git-svn will be updated to the
  45         latest revision.
  46
  47         Note: You should never attempt to modify the remotes/git-svn
  48         branch outside of git-svn.  Instead, create a branch from
  49         remotes/git-svn and work on that branch.  Use the 'commit'
  50         command (see below) to write git commits back to
  51         remotes/git-svn.
  52
  53         See 'Additional Fetch Arguments' if you are interested in
  54         manually joining branches on commit.
  55
  56 commit::
  57         Commit specified commit or tree objects to SVN.  This relies on
  58         your imported fetch data being up-to-date.  This makes
  59         absolutely no attempts to do patching when committing to SVN, it
  60         simply overwrites files with those specified in the tree or
  61         commit.  All merging is assumed to have taken place
  62         independently of git-svn functions.
  63
  64 rebuild::
  65         Not a part of daily usage, but this is a useful command if
  66         you've just cloned a repository (using git-clone) that was
  67         tracked with git-svn.  Unfortunately, git-clone does not clone
  68         git-svn metadata and the svn working tree that git-svn uses for
  69         its operations.  This rebuilds the metadata so git-svn can
  70         resume fetch operations.  A Subversion URL may be optionally
  71         specified at the command-line if the directory/repository you're
  72         tracking has moved or changed protocols.
  73
  74 show-ignore::
  75         Recursively finds and lists the svn:ignore property on
  76         directories.  The output is suitable for appending to
  77         the $GIT_DIR/info/exclude file.
  78
  79 OPTIONS
  80 -------
  81 -r <ARG>::
  82 --revision <ARG>::
  83         Only used with the 'fetch' command.
  84
  85         Takes any valid -r<argument> svn would accept and passes it
  86         directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax
  87         is also supported.  This is passed directly to svn, see svn
  88         documentation for more details.
  89
  90         This can allow you to make partial mirrors when running fetch.
  91
  92 -::
  93 --stdin::
  94         Only used with the 'commit' command.
  95
  96         Read a list of commits from stdin and commit them in reverse
  97         order.  Only the leading sha1 is read from each line, so
  98         git-rev-list --pretty=oneline output can be used.
  99
 100 --rmdir::
 101         Only used with the 'commit' command.
 102
 103         Remove directories from the SVN tree if there are no files left
 104         behind.  SVN can version empty directories, and they are not
 105         removed by default if there are no files left in them.  git
 106         cannot version empty directories.  Enabling this flag will make
 107         the commit to SVN act like git.
 108
 109         repo-config key: svn.rmdir
 110
 111 -e::
 112 --edit::
 113         Only used with the 'commit' command.
 114
 115         Edit the commit message before committing to SVN.  This is off by
 116         default for objects that are commits, and forced on when committing
 117         tree objects.
 118
 119         repo-config key: svn.edit
 120
 121 -l<num>::
 122 --find-copies-harder::
 123         Both of these are only used with the 'commit' command.
 124
 125         They are both passed directly to git-diff-tree see
 126         git-diff-tree(1) for more information.
 127
 128         repo-config key: svn.l
 129         repo-config key: svn.findcopiesharder
 130
 131 -A<filename>::
 132 --authors-file=<filename>::
 133
 134         Syntax is compatible with the files used by git-svnimport and
 135         git-cvsimport:
 136
 137 ------------------------------------------------------------------------
 138 loginname = Joe User <user@example.com>
 139 ------------------------------------------------------------------------
 140
 141         If this option is specified and git-svn encounters an SVN
 142         committer name that does not exist in the authors-file, git-svn
 143         will abort operation. The user will then have to add the
 144         appropriate entry.  Re-running the previous git-svn command
 145         after the authors-file is modified should continue operation.
 146
 147         repo-config key: svn.authors-file
 148
 149 ADVANCED OPTIONS
 150 ----------------
 151 -b<refname>::
 152 --branch <refname>::
 153         Used with 'fetch' or 'commit'.
 154
 155         This can be used to join arbitrary git branches to remotes/git-svn
 156         on new commits where the tree object is equivalent.
 157
 158         When used with different GIT_SVN_ID values, tags and branches in
 159         SVN can be tracked this way, as can some merges where the heads
 160         end up having completely equivalent content.  This can even be
 161         used to track branches across multiple SVN _repositories_.
 162
 163         This option may be specified multiple times, once for each
 164         branch.
 165
 166         repo-config key: svn.branch
 167
 168 -i<GIT_SVN_ID>::
 169 --id <GIT_SVN_ID>::
 170         This sets GIT_SVN_ID (instead of using the environment).  See
 171         the section on "Tracking Multiple Repositories or Branches" for
 172         more information on using GIT_SVN_ID.
 173
 174 COMPATIBILITY OPTIONS
 175 ---------------------
 176 --upgrade::
 177         Only used with the 'rebuild' command.
 178
 179         Run this if you used an old version of git-svn that used
 180         "git-svn-HEAD" instead of "remotes/git-svn" as the branch
 181         for tracking the remote.
 182
 183 --no-ignore-externals::
 184         Only used with the 'fetch' and 'rebuild' command.
 185
 186         By default, git-svn passes --ignore-externals to svn to avoid
 187         fetching svn:external trees into git.  Pass this flag to enable
 188         externals tracking directly via git.
 189
 190         Versions of svn that do not support --ignore-externals are
 191         automatically detected and this flag will be automatically
 192         enabled for them.
 193
 194         Otherwise, do not enable this flag unless you know what you're
 195         doing.
 196
 197         repo-config key: svn.noignoreexternals
 198
 199 Basic Examples
 200 ~~~~~~~~~~~~~~
 201
 202 Tracking and contributing to an Subversion managed-project:
 203
 204 ------------------------------------------------------------------------
 205 # Initialize a tree (like git init-db):
 206         git-svn init http://svn.foo.org/project/trunk
 207 # Fetch remote revisions:
 208         git-svn fetch
 209 # Create your own branch to hack on:
 210         git checkout -b my-branch remotes/git-svn
 211 # Commit only the git commits you want to SVN:
 212         git-svn commit <tree-ish> [<tree-ish_2> ...]
 213 # Commit all the git commits from my-branch that don't exist in SVN:
 214         git-svn commit remotes/git-svn..my-branch
 215 # Something is committed to SVN, pull the latest into your branch:
 216         git-svn fetch && git pull . remotes/git-svn
 217 # Append svn:ignore settings to the default git exclude file:
 218         git-svn show-ignore >> .git/info/exclude
 219 ------------------------------------------------------------------------
 220
 221 DESIGN PHILOSOPHY
 222 -----------------
 223 Merge tracking in Subversion is lacking and doing branched development
 224 with Subversion is cumbersome as a result.  git-svn completely forgoes
 225 any automated merge/branch tracking on the Subversion side and leaves it
 226 entirely up to the user on the git side.  It's simply not worth it to do
 227 a useful translation when the the original signal is weak.
 228
 229 TRACKING MULTIPLE REPOSITORIES OR BRANCHES
 230 ------------------------------------------
 231 This is for advanced users, most users should ignore this section.
 232
 233 Because git-svn does not care about relationships between different
 234 branches or directories in a Subversion repository, git-svn has a simple
 235 hack to allow it to track an arbitrary number of related _or_ unrelated
 236 SVN repositories via one git repository.  Simply set the GIT_SVN_ID
 237 environment variable to a name other other than "git-svn" (the default)
 238 and git-svn will ignore the contents of the $GIT_DIR/git-svn directory
 239 and instead do all of its work in $GIT_DIR/$GIT_SVN_ID for that
 240 invocation.  The interface branch will be remotes/$GIT_SVN_ID, instead of
 241 remotes/git-svn.  Any remotes/$GIT_SVN_ID branch should never be modified
 242 by the user outside of git-svn commands.
 243
 244 ADDITIONAL FETCH ARGUMENTS
 245 --------------------------
 246 This is for advanced users, most users should ignore this section.
 247
 248 Unfetched SVN revisions may be imported as children of existing commits
 249 by specifying additional arguments to 'fetch'.  Additional parents may
 250 optionally be specified in the form of sha1 hex sums at the
 251 command-line.  Unfetched SVN revisions may also be tied to particular
 252 git commits with the following syntax:
 253
 254         svn_revision_number=git_commit_sha1
 255
 256 This allows you to tie unfetched SVN revision 375 to your current HEAD::
 257
 258         `git-svn fetch 375=$(git-rev-parse HEAD)`
 259
 260 Advanced Example: Tracking a Reorganized Repository
 261 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 262 If you're tracking a directory that has moved, or otherwise been
 263 branched or tagged off of another directory in the repository and you
 264 care about the full history of the project, then you can read this
 265 section.
 266
 267 This is how Yann Dirson tracked the trunk of the ufoai directory when
 268 the /trunk directory of his repository was moved to /ufoai/trunk and
 269 he needed to continue tracking /ufoai/trunk where /trunk left off.
 270
 271 ------------------------------------------------------------------------
 272         # This log message shows when the repository was reorganized:
 273         r166 | ydirson | 2006-03-02 01:36:55 +0100 (Thu, 02 Mar 2006) | 1 line
 274         Changed paths:
 275            D /trunk
 276            A /ufoai/trunk (from /trunk:165)
 277
 278         # First we start tracking the old revisions:
 279         GIT_SVN_ID=git-oldsvn git-svn init \
 280                         https://svn.sourceforge.net/svnroot/ufoai/trunk
 281         GIT_SVN_ID=git-oldsvn git-svn fetch -r1:165
 282
 283         # And now, we continue tracking the new revisions:
 284         GIT_SVN_ID=git-newsvn git-svn init \
 285               https://svn.sourceforge.net/svnroot/ufoai/ufoai/trunk
 286         GIT_SVN_ID=git-newsvn git-svn fetch \
 287               166=`git-rev-parse refs/remotes/git-oldsvn`
 288 ------------------------------------------------------------------------
 289
 290 BUGS
 291 ----
 292 If somebody commits a conflicting changeset to SVN at a bad moment
 293 (right before you commit) causing a conflict and your commit to fail,
 294 your svn working tree ($GIT_DIR/git-svn/tree) may be dirtied.  The
 295 easiest thing to do is probably just to rm -rf $GIT_DIR/git-svn/tree and
 296 run 'rebuild'.
 297
 298 We ignore all SVN properties except svn:executable.  Too difficult to
 299 map them since we rely heavily on git write-tree being _exactly_ the
 300 same on both the SVN and git working trees and I prefer not to clutter
 301 working trees with metadata files.
 302
 303 svn:keywords can't be ignored in Subversion (at least I don't know of
 304 a way to ignore them).
 305
 306 Renamed and copied directories are not detected by git and hence not
 307 tracked when committing to SVN.  I do not plan on adding support for
 308 this as it's quite difficult and time-consuming to get working for all
 309 the possible corner cases (git doesn't do it, either).  Renamed and
 310 copied files are fully supported if they're similar enough for git to
 311 detect them.
 312
 313 Author
 314 ------
 315 Written by Eric Wong <normalperson@yhbt.net>.
 316
 317 Documentation
 318 -------------
 319 Written by Eric Wong <normalperson@yhbt.net>.