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 --ignore-nodate::
 248 Only used with the 'fetch' command.
 249
 250 By default git-svn will crash if it tries to import a revision
 251 from SVN which has '(no date)' listed as the date of the revision.
 252 This is repository corruption on SVN's part, plain and simple.
 253 But sometimes you really need those revisions anyway.
 254
 255 If supplied git-svn will convert '(no date)' entries to the UNIX
 256 epoch (midnight on Jan. 1, 1970).  Yes, that's probably very wrong.
 257 SVN was very wrong.
 258
 259 --
 260
 261 Basic Examples
 262 ~~~~~~~~~~~~~~
 263
 264 Tracking and contributing to an Subversion managed-project:
 265
 266 ------------------------------------------------------------------------
 267 # Initialize a tree (like git init-db):
 268         git-svn init http://svn.foo.org/project/trunk
 269 # Fetch remote revisions:
 270         git-svn fetch
 271 # Create your own branch to hack on:
 272         git checkout -b my-branch remotes/git-svn
 273 # Commit only the git commits you want to SVN:
 274         git-svn commit <tree-ish> [<tree-ish_2> ...]
 275 # Commit all the git commits from my-branch that don't exist in SVN:
 276         git-svn commit remotes/git-svn..my-branch
 277 # Something is committed to SVN, rebase the latest into your branch:
 278         git-svn fetch && git rebase remotes/git-svn
 279 # Append svn:ignore settings to the default git exclude file:
 280         git-svn show-ignore >> .git/info/exclude
 281 ------------------------------------------------------------------------
 282
 283 REBASE VS. PULL
 284 ---------------
 285
 286 Originally, git-svn recommended that the remotes/git-svn branch be
 287 pulled from.  This is because the author favored 'git-svn commit B'
 288 to commit a single head rather than the 'git-svn commit A..B' notation
 289 to commit multiple commits.
 290
 291 If you use 'git-svn commit A..B' to commit several diffs and you do not
 292 have the latest remotes/git-svn merged into my-branch, you should use
 293 'git rebase' to update your work branch instead of 'git pull'.  'pull'
 294 can cause non-linear history to be flattened when committing into SVN,
 295 which can lead to merge commits reversing previous commits in SVN.
 296
 297 DESIGN PHILOSOPHY
 298 -----------------
 299 Merge tracking in Subversion is lacking and doing branched development
 300 with Subversion is cumbersome as a result.  git-svn completely forgoes
 301 any automated merge/branch tracking on the Subversion side and leaves it
 302 entirely up to the user on the git side.  It's simply not worth it to do
 303 a useful translation when the original signal is weak.
 304
 305 [[tracking-multiple-repos]]
 306 TRACKING MULTIPLE REPOSITORIES OR BRANCHES
 307 ------------------------------------------
 308 This is for advanced users, most users should ignore this section.
 309
 310 Because git-svn does not care about relationships between different
 311 branches or directories in a Subversion repository, git-svn has a simple
 312 hack to allow it to track an arbitrary number of related _or_ unrelated
 313 SVN repositories via one git repository.  Simply set the GIT_SVN_ID
 314 environment variable to a name other other than "git-svn" (the default)
 315 and git-svn will ignore the contents of the $GIT_DIR/git-svn directory
 316 and instead do all of its work in $GIT_DIR/$GIT_SVN_ID for that
 317 invocation.  The interface branch will be remotes/$GIT_SVN_ID, instead of
 318 remotes/git-svn.  Any remotes/$GIT_SVN_ID branch should never be modified
 319 by the user outside of git-svn commands.
 320
 321 [[fetch-args]]
 322 ADDITIONAL FETCH ARGUMENTS
 323 --------------------------
 324 This is for advanced users, most users should ignore this section.
 325
 326 Unfetched SVN revisions may be imported as children of existing commits
 327 by specifying additional arguments to 'fetch'.  Additional parents may
 328 optionally be specified in the form of sha1 hex sums at the
 329 command-line.  Unfetched SVN revisions may also be tied to particular
 330 git commits with the following syntax:
 331
 332 ------------------------------------------------
 333         svn_revision_number=git_commit_sha1
 334 ------------------------------------------------
 335
 336 This allows you to tie unfetched SVN revision 375 to your current HEAD:
 337
 338 ------------------------------------------------
 339         git-svn fetch 375=$(git-rev-parse HEAD)
 340 ------------------------------------------------
 341
 342 Advanced Example: Tracking a Reorganized Repository
 343 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 344 If you're tracking a directory that has moved, or otherwise been
 345 branched or tagged off of another directory in the repository and you
 346 care about the full history of the project, then you can read this
 347 section.
 348
 349 This is how Yann Dirson tracked the trunk of the ufoai directory when
 350 the /trunk directory of his repository was moved to /ufoai/trunk and
 351 he needed to continue tracking /ufoai/trunk where /trunk left off.
 352
 353 ------------------------------------------------------------------------
 354         # This log message shows when the repository was reorganized:
 355         r166 | ydirson | 2006-03-02 01:36:55 +0100 (Thu, 02 Mar 2006) | 1 line
 356         Changed paths:
 357            D /trunk
 358            A /ufoai/trunk (from /trunk:165)
 359
 360         # First we start tracking the old revisions:
 361         GIT_SVN_ID=git-oldsvn git-svn init \
 362                         https://svn.sourceforge.net/svnroot/ufoai/trunk
 363         GIT_SVN_ID=git-oldsvn git-svn fetch -r1:165
 364
 365         # And now, we continue tracking the new revisions:
 366         GIT_SVN_ID=git-newsvn git-svn init \
 367               https://svn.sourceforge.net/svnroot/ufoai/ufoai/trunk
 368         GIT_SVN_ID=git-newsvn git-svn fetch \
 369               166=`git-rev-parse refs/remotes/git-oldsvn`
 370 ------------------------------------------------------------------------
 371
 372 BUGS
 373 ----
 374 If somebody commits a conflicting changeset to SVN at a bad moment
 375 (right before you commit) causing a conflict and your commit to fail,
 376 your svn working tree ($GIT_DIR/git-svn/tree) may be dirtied.  The
 377 easiest thing to do is probably just to rm -rf $GIT_DIR/git-svn/tree and
 378 run 'rebuild'.
 379
 380 We ignore all SVN properties except svn:executable.  Too difficult to
 381 map them since we rely heavily on git write-tree being _exactly_ the
 382 same on both the SVN and git working trees and I prefer not to clutter
 383 working trees with metadata files.
 384
 385 svn:keywords can't be ignored in Subversion (at least I don't know of
 386 a way to ignore them).
 387
 388 Renamed and copied directories are not detected by git and hence not
 389 tracked when committing to SVN.  I do not plan on adding support for
 390 this as it's quite difficult and time-consuming to get working for all
 391 the possible corner cases (git doesn't do it, either).  Renamed and
 392 copied files are fully supported if they're similar enough for git to
 393 detect them.
 394
 395 SEE ALSO
 396 --------
 397 gitlink:git-rebase[1]
 398
 399 Author
 400 ------
 401 Written by Eric Wong <normalperson@yhbt.net>.
 402
 403 Documentation
 404 -------------
 405 Written by Eric Wong <normalperson@yhbt.net>.