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 Subversion and git.
  15 It is not to be confused with gitlink:git-svnimport[1], which is
  16 read-only and geared towards tracking multiple branches.
  17
  18 git-svn was originally 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.  Since its inception,
  21 git-svn has gained the ability to track multiple branches in a manner
  22 similar to git-svnimport; but it cannot (yet) automatically detect new
  23 branches and tags like git-svnimport does.
  24
  25 git-svn is especially useful when it comes to tracking repositories
  26 not organized in the way Subversion developers recommend (trunk,
  27 branches, tags directories).
  28
  29 COMMANDS
  30 --------
  31 --
  32
  33 'init'::
  34         Creates an empty git repository with additional metadata
  35         directories for git-svn.  The Subversion URL must be specified
  36         as a command-line argument.  Optionally, the target directory
  37         to operate on can be specified as a second argument.  Normally
  38         this command initializes the current directory.
  39
  40 'fetch'::
  41
  42 Fetch unfetched revisions from the Subversion URL we are
  43 tracking.  refs/remotes/git-svn will be updated to the
  44 latest revision.
  45
  46 Note: You should never attempt to modify the remotes/git-svn
  47 branch outside of git-svn.  Instead, create a branch from
  48 remotes/git-svn and work on that branch.  Use the 'dcommit'
  49 command (see below) to write git commits back to
  50 remotes/git-svn.
  51
  52 See '<<fetch-args,Additional Fetch Arguments>>' if you are interested in
  53 manually joining branches on commit.
  54
  55 'dcommit'::
  56         Commit each diff from a specified head directly to the SVN
  57         repository, and then rebase or reset (depending on whether or
  58         not there is a diff between SVN and head).  This will create
  59         a revision in SVN for each commit in git.
  60         It is recommended that you run git-svn fetch and rebase (not
  61         pull or merge) your commits against the latest changes in the
  62         SVN repository.
  63         An optional command-line argument may be specified as an
  64         alternative to HEAD.
  65         This is advantageous over 'set-tree' (below) because it produces
  66         cleaner, more linear history.
  67
  68 'log'::
  69         This should make it easy to look up svn log messages when svn
  70         users refer to -r/--revision numbers.
  71
  72         The following features from `svn log' are supported:
  73
  74         --revision=<n>[:<n>] - is supported, non-numeric args are not:
  75                                HEAD, NEXT, BASE, PREV, etc ...
  76         -v/--verbose         - it's not completely compatible with
  77                                the --verbose output in svn log, but
  78                                reasonably close.
  79         --limit=<n>          - is NOT the same as --max-count,
  80                                doesn't count merged/excluded commits
  81         --incremental        - supported
  82
  83         New features:
  84
  85         --show-commit        - shows the git commit sha1, as well
  86         --oneline            - our version of --pretty=oneline
  87
  88         Any other arguments are passed directly to `git log'
  89
  90 'set-tree'::
  91         You should consider using 'dcommit' instead of this command.
  92         Commit specified commit or tree objects to SVN.  This relies on
  93         your imported fetch data being up-to-date.  This makes
  94         absolutely no attempts to do patching when committing to SVN, it
  95         simply overwrites files with those specified in the tree or
  96         commit.  All merging is assumed to have taken place
  97         independently of git-svn functions.
  98
  99 'rebuild'::
 100         Not a part of daily usage, but this is a useful command if
 101         you've just cloned a repository (using gitlink:git-clone[1]) that was
 102         tracked with git-svn.  Unfortunately, git-clone does not clone
 103         git-svn metadata and the svn working tree that git-svn uses for
 104         its operations.  This rebuilds the metadata so git-svn can
 105         resume fetch operations.  A Subversion URL may be optionally
 106         specified at the command-line if the directory/repository you're
 107         tracking has moved or changed protocols.
 108
 109 'show-ignore'::
 110         Recursively finds and lists the svn:ignore property on
 111         directories.  The output is suitable for appending to
 112         the $GIT_DIR/info/exclude file.
 113
 114 'commit-diff'::
 115         Commits the diff of two tree-ish arguments from the
 116         command-line.  This command is intended for interoperability with
 117         git-svnimport and does not rely on being inside an git-svn
 118         init-ed repository.  This command takes three arguments, (a) the
 119         original tree to diff against, (b) the new tree result, (c) the
 120         URL of the target Subversion repository.  The final argument
 121         (URL) may be omitted if you are working from a git-svn-aware
 122         repository (that has been init-ed with git-svn).
 123         The -r<revision> option is required for this.
 124
 125 'graft-branches'::
 126         This command attempts to detect merges/branches from already
 127         imported history.  Techniques used currently include regexes,
 128         file copies, and tree-matches).  This command generates (or
 129         modifies) the $GIT_DIR/info/grafts file.  This command is
 130         considered experimental, and inherently flawed because
 131         merge-tracking in SVN is inherently flawed and inconsistent
 132         across different repositories.
 133
 134 'multi-init'::
 135         This command supports git-svnimport-like command-line syntax for
 136         importing repositories that are laid out as recommended by the
 137         SVN folks.  This is a bit more tolerant than the git-svnimport
 138         command-line syntax and doesn't require the user to figure out
 139         where the repository URL ends and where the repository path
 140         begins.
 141
 142 -T<trunk_subdir>::
 143 --trunk=<trunk_subdir>::
 144 -t<tags_subdir>::
 145 --tags=<tags_subdir>::
 146 -b<branches_subdir>::
 147 --branches=<branches_subdir>::
 148         These are the command-line options for multi-init.  Each of
 149         these flags can point to a relative repository path
 150         (--tags=project/tags') or a full url
 151         (--tags=https://foo.org/project/tags)
 152
 153 --prefix=<prefix>
 154         This allows one to specify a prefix which is prepended to the
 155         names of remotes.  The prefix does not automatically include a
 156         trailing slash, so be sure you include one in the argument if
 157         that is what you want.  This is useful if you wish to track
 158         multiple projects that share a common repository.
 159
 160 'multi-fetch'::
 161         This runs fetch on all known SVN branches we're tracking.  This
 162         will NOT discover new branches (unlike git-svnimport), so
 163         multi-init will need to be re-run (it's idempotent).
 164
 165 --
 166
 167 OPTIONS
 168 -------
 169 --
 170
 171 --shared::
 172 --template=<template_directory>::
 173         Only used with the 'init' command.
 174         These are passed directly to gitlink:git-init[1].
 175
 176 -r <ARG>::
 177 --revision <ARG>::
 178
 179 Only used with the 'fetch' command.
 180
 181 Takes any valid -r<argument> svn would accept and passes it
 182 directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax
 183 is also supported.  This is passed directly to svn, see svn
 184 documentation for more details.
 185
 186 This can allow you to make partial mirrors when running fetch.
 187
 188 -::
 189 --stdin::
 190
 191 Only used with the 'set-tree' command.
 192
 193 Read a list of commits from stdin and commit them in reverse
 194 order.  Only the leading sha1 is read from each line, so
 195 git-rev-list --pretty=oneline output can be used.
 196
 197 --rmdir::
 198
 199 Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
 200
 201 Remove directories from the SVN tree if there are no files left
 202 behind.  SVN can version empty directories, and they are not
 203 removed by default if there are no files left in them.  git
 204 cannot version empty directories.  Enabling this flag will make
 205 the commit to SVN act like git.
 206
 207 config key: svn.rmdir
 208
 209 -e::
 210 --edit::
 211
 212 Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
 213
 214 Edit the commit message before committing to SVN.  This is off by
 215 default for objects that are commits, and forced on when committing
 216 tree objects.
 217
 218 config key: svn.edit
 219
 220 -l<num>::
 221 --find-copies-harder::
 222
 223 Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
 224
 225 They are both passed directly to git-diff-tree see
 226 gitlink:git-diff-tree[1] for more information.
 227
 228 [verse]
 229 config key: svn.l
 230 config key: svn.findcopiesharder
 231
 232 -A<filename>::
 233 --authors-file=<filename>::
 234
 235 Syntax is compatible with the files used by git-svnimport and
 236 git-cvsimport:
 237
 238 ------------------------------------------------------------------------
 239         loginname = Joe User <user@example.com>
 240 ------------------------------------------------------------------------
 241
 242 If this option is specified and git-svn encounters an SVN
 243 committer name that does not exist in the authors-file, git-svn
 244 will abort operation. The user will then have to add the
 245 appropriate entry.  Re-running the previous git-svn command
 246 after the authors-file is modified should continue operation.
 247
 248 config key: svn.authorsfile
 249
 250 -q::
 251 --quiet::
 252         Make git-svn less verbose.
 253
 254 --repack[=<n>]::
 255 --repack-flags=<flags>
 256         These should help keep disk usage sane for large fetches
 257         with many revisions.
 258
 259         --repack takes an optional argument for the number of revisions
 260         to fetch before repacking.  This defaults to repacking every
 261         1000 commits fetched if no argument is specified.
 262
 263         --repack-flags are passed directly to gitlink:git-repack[1].
 264
 265 config key: svn.repack
 266 config key: svn.repackflags
 267
 268 -m::
 269 --merge::
 270 -s<strategy>::
 271 --strategy=<strategy>::
 272
 273 These are only used with the 'dcommit' command.
 274
 275 Passed directly to git-rebase when using 'dcommit' if a
 276 'git-reset' cannot be used (see dcommit).
 277
 278 -n::
 279 --dry-run::
 280
 281 This is only used with the 'dcommit' command.
 282
 283 Print out the series of git arguments that would show
 284 which diffs would be committed to SVN.
 285
 286 --
 287
 288 ADVANCED OPTIONS
 289 ----------------
 290 --
 291
 292 -b<refname>::
 293 --branch <refname>::
 294 Used with 'fetch', 'dcommit' or 'set-tree'.
 295
 296 This can be used to join arbitrary git branches to remotes/git-svn
 297 on new commits where the tree object is equivalent.
 298
 299 When used with different GIT_SVN_ID values, tags and branches in
 300 SVN can be tracked this way, as can some merges where the heads
 301 end up having completely equivalent content.  This can even be
 302 used to track branches across multiple SVN _repositories_.
 303
 304 This option may be specified multiple times, once for each
 305 branch.
 306
 307 config key: svn.branch
 308
 309 -i<GIT_SVN_ID>::
 310 --id <GIT_SVN_ID>::
 311
 312 This sets GIT_SVN_ID (instead of using the environment).  See the
 313 section on
 314 '<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>'
 315 for more information on using GIT_SVN_ID.
 316
 317 --follow-parent::
 318         This is especially helpful when we're tracking a directory
 319         that has been moved around within the repository, or if we
 320         started tracking a branch and never tracked the trunk it was
 321         descended from.
 322
 323 config key: svn.followparent
 324
 325 --no-metadata::
 326         This gets rid of the git-svn-id: lines at the end of every commit.
 327
 328         With this, you lose the ability to use the rebuild command.  If
 329         you ever lose your .git/svn/git-svn/.rev_db file, you won't be
 330         able to fetch again, either.  This is fine for one-shot imports.
 331
 332         The 'git-svn log' command will not work on repositories using this,
 333         either.
 334
 335 config key: svn.nometadata
 336
 337 --
 338
 339 COMPATIBILITY OPTIONS
 340 ---------------------
 341 --
 342
 343 --upgrade::
 344 Only used with the 'rebuild' command.
 345
 346 Run this if you used an old version of git-svn that used
 347 "git-svn-HEAD" instead of "remotes/git-svn" as the branch
 348 for tracking the remote.
 349
 350 --ignore-nodate::
 351 Only used with the 'fetch' command.
 352
 353 By default git-svn will crash if it tries to import a revision
 354 from SVN which has '(no date)' listed as the date of the revision.
 355 This is repository corruption on SVN's part, plain and simple.
 356 But sometimes you really need those revisions anyway.
 357
 358 If supplied git-svn will convert '(no date)' entries to the UNIX
 359 epoch (midnight on Jan. 1, 1970).  Yes, that's probably very wrong.
 360 SVN was very wrong.
 361
 362 --
 363
 364 Basic Examples
 365 ~~~~~~~~~~~~~~
 366
 367 Tracking and contributing to a the trunk of a Subversion-managed project:
 368
 369 ------------------------------------------------------------------------
 370 # Initialize a repo (like git init):
 371         git-svn init http://svn.foo.org/project/trunk
 372 # Fetch remote revisions:
 373         git-svn fetch
 374 # Create your own branch to hack on:
 375         git checkout -b my-branch remotes/git-svn
 376 # Do some work, and then commit your new changes to SVN, as well as
 377 # automatically updating your working HEAD:
 378         git-svn dcommit
 379 # Something is committed to SVN, rebase the latest into your branch:
 380         git-svn fetch && git rebase remotes/git-svn
 381 # Append svn:ignore settings to the default git exclude file:
 382         git-svn show-ignore >> .git/info/exclude
 383 ------------------------------------------------------------------------
 384
 385 Tracking and contributing to an entire Subversion-managed project
 386 (complete with a trunk, tags and branches):
 387 See also:
 388 '<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>'
 389
 390 ------------------------------------------------------------------------
 391 # Initialize a repo (like git init):
 392         git-svn multi-init http://svn.foo.org/project \
 393                 -T trunk -b branches -t tags
 394 # Fetch remote revisions:
 395         git-svn multi-fetch
 396 # Create your own branch of trunk to hack on:
 397         git checkout -b my-trunk remotes/trunk
 398 # Do some work, and then commit your new changes to SVN, as well as
 399 # automatically updating your working HEAD:
 400         git-svn dcommit -i trunk
 401 # Something has been committed to trunk, rebase the latest into your branch:
 402         git-svn multi-fetch && git rebase remotes/trunk
 403 # Append svn:ignore settings of trunk to the default git exclude file:
 404         git-svn show-ignore -i trunk >> .git/info/exclude
 405 # Check for new branches and tags (no arguments are needed):
 406         git-svn multi-init
 407 ------------------------------------------------------------------------
 408
 409 REBASE VS. PULL/MERGE
 410 ---------------------
 411
 412 Originally, git-svn recommended that the remotes/git-svn branch be
 413 pulled or merged from.  This is because the author favored
 414 'git-svn set-tree B' to commit a single head rather than the
 415 'git-svn set-tree A..B' notation to commit multiple commits.
 416
 417 If you use 'git-svn set-tree A..B' to commit several diffs and you do
 418 not have the latest remotes/git-svn merged into my-branch, you should
 419 use 'git rebase' to update your work branch instead of 'git pull' or
 420 'git merge'.  'pull/merge' can cause non-linear history to be flattened
 421 when committing into SVN, which can lead to merge commits reversing
 422 previous commits in SVN.
 423
 424 DESIGN PHILOSOPHY
 425 -----------------
 426 Merge tracking in Subversion is lacking and doing branched development
 427 with Subversion is cumbersome as a result.  git-svn does not do
 428 automated merge/branch tracking by default and leaves it entirely up to
 429 the user on the git side.
 430
 431 [[tracking-multiple-repos]]
 432 TRACKING MULTIPLE REPOSITORIES OR BRANCHES
 433 ------------------------------------------
 434 Because git-svn does not care about relationships between different
 435 branches or directories in a Subversion repository, git-svn has a simple
 436 hack to allow it to track an arbitrary number of related _or_ unrelated
 437 SVN repositories via one git repository.  Simply use the --id/-i flag or
 438 set the GIT_SVN_ID environment variable to a name other other than
 439 "git-svn" (the default) and git-svn will ignore the contents of the
 440 $GIT_DIR/svn/git-svn directory and instead do all of its work in
 441 $GIT_DIR/svn/$GIT_SVN_ID for that invocation.  The interface branch will
 442 be remotes/$GIT_SVN_ID, instead of remotes/git-svn.  Any
 443 remotes/$GIT_SVN_ID branch should never be modified by the user outside
 444 of git-svn commands.
 445
 446 [[fetch-args]]
 447 ADDITIONAL FETCH ARGUMENTS
 448 --------------------------
 449 This is for advanced users, most users should ignore this section.
 450
 451 Unfetched SVN revisions may be imported as children of existing commits
 452 by specifying additional arguments to 'fetch'.  Additional parents may
 453 optionally be specified in the form of sha1 hex sums at the
 454 command-line.  Unfetched SVN revisions may also be tied to particular
 455 git commits with the following syntax:
 456
 457 ------------------------------------------------
 458         svn_revision_number=git_commit_sha1
 459 ------------------------------------------------
 460
 461 This allows you to tie unfetched SVN revision 375 to your current HEAD:
 462
 463 ------------------------------------------------
 464         git-svn fetch 375=$(git-rev-parse HEAD)
 465 ------------------------------------------------
 466
 467 If you're tracking a directory that has moved, or otherwise been
 468 branched or tagged off of another directory in the repository and you
 469 care about the full history of the project, then you can use
 470 the --follow-parent option.
 471
 472 ------------------------------------------------
 473         git-svn fetch --follow-parent
 474 ------------------------------------------------
 475
 476 BUGS
 477 ----
 478
 479 We ignore all SVN properties except svn:executable.  Too difficult to
 480 map them since we rely heavily on git write-tree being _exactly_ the
 481 same on both the SVN and git working trees and I prefer not to clutter
 482 working trees with metadata files.
 483
 484 Renamed and copied directories are not detected by git and hence not
 485 tracked when committing to SVN.  I do not plan on adding support for
 486 this as it's quite difficult and time-consuming to get working for all
 487 the possible corner cases (git doesn't do it, either).  Renamed and
 488 copied files are fully supported if they're similar enough for git to
 489 detect them.
 490
 491 SEE ALSO
 492 --------
 493 gitlink:git-rebase[1]
 494
 495 Author
 496 ------
 497 Written by Eric Wong <normalperson@yhbt.net>.
 498
 499 Documentation
 500 -------------
 501 Written by Eric Wong <normalperson@yhbt.net>.