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