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.
  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.
  23
  24 git-svn is especially useful when it comes to tracking repositories
  25 not organized in the way Subversion developers recommend (trunk,
  26 branches, tags directories).
  27
  28 COMMANDS
  29 --------
  30 --
  31
  32 'init'::
  33         Initializes an empty git repository with additional
  34         metadata directories for git-svn.  The Subversion URL
  35         may be specified as a command-line argument, or as full
  36         URL arguments to -T/-t/-b.  Optionally, the target
  37         directory to operate on can be specified as a second
  38         argument.  Normally this command initializes the current
  39         directory.
  40
  41 -T<trunk_subdir>;;
  42 --trunk=<trunk_subdir>;;
  43 -t<tags_subdir>;;
  44 --tags=<tags_subdir>;;
  45 -b<branches_subdir>;;
  46 --branches=<branches_subdir>;;
  47         These are optional command-line options for init.  Each of
  48         these flags can point to a relative repository path
  49         (--tags=project/tags') or a full url
  50         (--tags=https://foo.org/project/tags)
  51 --no-metadata;;
  52         Set the 'noMetadata' option in the [svn-remote] config.
  53 --use-svm-props;;
  54         Set the 'useSvmProps' option in the [svn-remote] config.
  55 --use-svnsync-props;;
  56         Set the 'useSvnsyncProps' option in the [svn-remote] config.
  57 --rewrite-root=<URL>;;
  58         Set the 'rewriteRoot' option in the [svn-remote] config.
  59 --username=<USER>;;
  60         For transports that SVN handles authentication for (http,
  61         https, and plain svn), specify the username.  For other
  62         transports (eg svn+ssh://), you must include the username in
  63         the URL, eg svn+ssh://foo@svn.bar.com/project
  64 --prefix=<prefix>;;
  65         This allows one to specify a prefix which is prepended
  66         to the names of remotes if trunk/branches/tags are
  67         specified.  The prefix does not automatically include a
  68         trailing slash, so be sure you include one in the
  69         argument if that is what you want.  This is useful if
  70         you wish to track multiple projects that share a common
  71         repository.
  72
  73 'fetch'::
  74         Fetch unfetched revisions from the Subversion remote we are
  75         tracking.  The name of the [svn-remote "..."] section in the
  76         .git/config file may be specified as an optional command-line
  77         argument.
  78
  79 'clone'::
  80         Runs 'init' and 'fetch'.  It will automatically create a
  81         directory based on the basename of the URL passed to it;
  82         or if a second argument is passed; it will create a directory
  83         and work within that.  It accepts all arguments that the
  84         'init' and 'fetch' commands accept; with the exception of
  85         '--fetch-all'.   After a repository is cloned, the 'fetch'
  86         command will be able to update revisions without affecting
  87         the working tree; and the 'rebase' command will be able
  88         to update the working tree with the latest changes.
  89
  90 'rebase'::
  91         This fetches revisions from the SVN parent of the current HEAD
  92         and rebases the current (uncommitted to SVN) work against it.
  93
  94 This works similarly to 'svn update' or 'git-pull' except that
  95 it preserves linear history with 'git-rebase' instead of
  96 'git-merge' for ease of dcommit-ing with git-svn.
  97
  98 This accepts all options that 'git-svn fetch' and 'git-rebase'
  99 accepts.  However '--fetch-all' only fetches from the current
 100 [svn-remote], and not all [svn-remote] definitions.
 101
 102 Like 'git-rebase'; this requires that the working tree be clean
 103 and have no uncommitted changes.
 104
 105 -l;;
 106 --local;;
 107         Do not fetch remotely; only run 'git-rebase' against the
 108         last fetched commit from the upstream SVN.
 109
 110 'dcommit'::
 111         Commit each diff from a specified head directly to the SVN
 112         repository, and then rebase or reset (depending on whether or
 113         not there is a diff between SVN and head).  This will create
 114         a revision in SVN for each commit in git.
 115         It is recommended that you run git-svn fetch and rebase (not
 116         pull or merge) your commits against the latest changes in the
 117         SVN repository.
 118         An optional command-line argument may be specified as an
 119         alternative to HEAD.
 120         This is advantageous over 'set-tree' (below) because it produces
 121         cleaner, more linear history.
 122 +
 123 --no-rebase;;
 124         After committing, do not rebase or reset.
 125 --
 126
 127 'log'::
 128         This should make it easy to look up svn log messages when svn
 129         users refer to -r/--revision numbers.
 130 +
 131 The following features from `svn log' are supported:
 132 +
 133 --
 134 --revision=<n>[:<n>];;
 135         is supported, non-numeric args are not:
 136         HEAD, NEXT, BASE, PREV, etc ...
 137 -v/--verbose;;
 138         it's not completely compatible with the --verbose
 139         output in svn log, but reasonably close.
 140 --limit=<n>;;
 141         is NOT the same as --max-count, doesn't count
 142         merged/excluded commits
 143 --incremental;;
 144         supported
 145 --
 146 +
 147 New features:
 148 +
 149 --
 150 --show-commit;;
 151         shows the git commit sha1, as well
 152 --oneline;;
 153         our version of --pretty=oneline
 154 --
 155 +
 156 Any other arguments are passed directly to `git log'
 157
 158 --
 159 'find-rev'::
 160         When given an SVN revision number of the form 'rN', returns the
 161         corresponding git commit hash (this can optionally be followed by a
 162         tree-ish to specify which branch should be searched).  When given a
 163         tree-ish, returns the corresponding SVN revision number.
 164
 165 'set-tree'::
 166         You should consider using 'dcommit' instead of this command.
 167         Commit specified commit or tree objects to SVN.  This relies on
 168         your imported fetch data being up-to-date.  This makes
 169         absolutely no attempts to do patching when committing to SVN, it
 170         simply overwrites files with those specified in the tree or
 171         commit.  All merging is assumed to have taken place
 172         independently of git-svn functions.
 173
 174 'show-ignore'::
 175         Recursively finds and lists the svn:ignore property on
 176         directories.  The output is suitable for appending to
 177         the $GIT_DIR/info/exclude file.
 178
 179 'commit-diff'::
 180         Commits the diff of two tree-ish arguments from the
 181         command-line.  This command is intended for interoperability with
 182         git-svnimport and does not rely on being inside an git-svn
 183         init-ed repository.  This command takes three arguments, (a) the
 184         original tree to diff against, (b) the new tree result, (c) the
 185         URL of the target Subversion repository.  The final argument
 186         (URL) may be omitted if you are working from a git-svn-aware
 187         repository (that has been init-ed with git-svn).
 188         The -r<revision> option is required for this.
 189
 190 --
 191
 192 OPTIONS
 193 -------
 194 --
 195
 196 --shared[={false|true|umask|group|all|world|everybody}]::
 197 --template=<template_directory>::
 198         Only used with the 'init' command.
 199         These are passed directly to gitlink:git-init[1].
 200
 201 -r <ARG>::
 202 --revision <ARG>::
 203
 204 Used with the 'fetch' command.
 205
 206 This allows revision ranges for partial/cauterized history
 207 to be supported.  $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges),
 208 $NUMBER:HEAD, and BASE:$NUMBER are all supported.
 209
 210 This can allow you to make partial mirrors when running fetch;
 211 but is generally not recommended because history will be skipped
 212 and lost.
 213
 214 -::
 215 --stdin::
 216
 217 Only used with the 'set-tree' command.
 218
 219 Read a list of commits from stdin and commit them in reverse
 220 order.  Only the leading sha1 is read from each line, so
 221 git-rev-list --pretty=oneline output can be used.
 222
 223 --rmdir::
 224
 225 Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
 226
 227 Remove directories from the SVN tree if there are no files left
 228 behind.  SVN can version empty directories, and they are not
 229 removed by default if there are no files left in them.  git
 230 cannot version empty directories.  Enabling this flag will make
 231 the commit to SVN act like git.
 232
 233 config key: svn.rmdir
 234
 235 -e::
 236 --edit::
 237
 238 Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
 239
 240 Edit the commit message before committing to SVN.  This is off by
 241 default for objects that are commits, and forced on when committing
 242 tree objects.
 243
 244 config key: svn.edit
 245
 246 -l<num>::
 247 --find-copies-harder::
 248
 249 Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
 250
 251 They are both passed directly to git-diff-tree see
 252 gitlink:git-diff-tree[1] for more information.
 253
 254 [verse]
 255 config key: svn.l
 256 config key: svn.findcopiesharder
 257
 258 -A<filename>::
 259 --authors-file=<filename>::
 260
 261 Syntax is compatible with the files used by git-svnimport and
 262 git-cvsimport:
 263
 264 ------------------------------------------------------------------------
 265         loginname = Joe User <user@example.com>
 266 ------------------------------------------------------------------------
 267
 268 If this option is specified and git-svn encounters an SVN
 269 committer name that does not exist in the authors-file, git-svn
 270 will abort operation. The user will then have to add the
 271 appropriate entry.  Re-running the previous git-svn command
 272 after the authors-file is modified should continue operation.
 273
 274 config key: svn.authorsfile
 275
 276 -q::
 277 --quiet::
 278         Make git-svn less verbose.
 279
 280 --repack[=<n>]::
 281 --repack-flags=<flags>::
 282
 283 These should help keep disk usage sane for large fetches
 284 with many revisions.
 285
 286 --repack takes an optional argument for the number of revisions
 287 to fetch before repacking.  This defaults to repacking every
 288 1000 commits fetched if no argument is specified.
 289
 290 --repack-flags are passed directly to gitlink:git-repack[1].
 291
 292 [verse]
 293 config key: svn.repack
 294 config key: svn.repackflags
 295
 296 -m::
 297 --merge::
 298 -s<strategy>::
 299 --strategy=<strategy>::
 300
 301 These are only used with the 'dcommit' and 'rebase' commands.
 302
 303 Passed directly to git-rebase when using 'dcommit' if a
 304 'git-reset' cannot be used (see dcommit).
 305
 306 -n::
 307 --dry-run::
 308
 309 This is only used with the 'dcommit' command.
 310
 311 Print out the series of git arguments that would show
 312 which diffs would be committed to SVN.
 313
 314 --
 315
 316 ADVANCED OPTIONS
 317 ----------------
 318 --
 319
 320 -i<GIT_SVN_ID>::
 321 --id <GIT_SVN_ID>::
 322
 323 This sets GIT_SVN_ID (instead of using the environment).  This
 324 allows the user to override the default refname to fetch from
 325 when tracking a single URL.  The 'log' and 'dcommit' commands
 326 no longer require this switch as an argument.
 327
 328 -R<remote name>::
 329 --svn-remote <remote name>::
 330         Specify the [svn-remote "<remote name>"] section to use,
 331         this allows SVN multiple repositories to be tracked.
 332         Default: "svn"
 333
 334 --follow-parent::
 335         This is especially helpful when we're tracking a directory
 336         that has been moved around within the repository, or if we
 337         started tracking a branch and never tracked the trunk it was
 338         descended from. This feature is enabled by default, use
 339         --no-follow-parent to disable it.
 340
 341 config key: svn.followparent
 342
 343 --
 344 CONFIG FILE-ONLY OPTIONS
 345 ------------------------
 346 --
 347
 348 svn.noMetadata::
 349 svn-remote.<name>.noMetadata::
 350
 351 This gets rid of the git-svn-id: lines at the end of every commit.
 352
 353 If you lose your .git/svn/git-svn/.rev_db file, git-svn will not
 354 be able to rebuild it and you won't be able to fetch again,
 355 either.  This is fine for one-shot imports.
 356
 357 The 'git-svn log' command will not work on repositories using
 358 this, either.  Using this conflicts with the 'useSvmProps'
 359 option for (hopefully) obvious reasons.
 360
 361 svn.useSvmProps::
 362 svn-remote.<name>.useSvmProps::
 363
 364 This allows git-svn to re-map repository URLs and UUIDs from
 365 mirrors created using SVN::Mirror (or svk) for metadata.
 366
 367 If an SVN revision has a property, "svm:headrev", it is likely
 368 that the revision was created by SVN::Mirror (also used by SVK).
 369 The property contains a repository UUID and a revision.  We want
 370 to make it look like we are mirroring the original URL, so
 371 introduce a helper function that returns the original identity
 372 URL and UUID, and use it when generating metadata in commit
 373 messages.
 374
 375 svn.useSvnsyncProps::
 376 svn-remote.<name>.useSvnsyncprops::
 377         Similar to the useSvmProps option; this is for users
 378         of the svnsync(1) command distributed with SVN 1.4.x and
 379         later.
 380
 381 svn-remote.<name>.rewriteRoot::
 382         This allows users to create repositories from alternate
 383         URLs.  For example, an administrator could run git-svn on the
 384         server locally (accessing via file://) but wish to distribute
 385         the repository with a public http:// or svn:// URL in the
 386         metadata so users of it will see the public URL.
 387
 388 Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps
 389 options all affect the metadata generated and used by git-svn; they
 390 *must* be set in the configuration file before any history is imported
 391 and these settings should never be changed once they are set.
 392
 393 Additionally, only one of these four options can be used per-svn-remote
 394 section because they affect the 'git-svn-id:' metadata line.
 395
 396 --
 397
 398 BASIC EXAMPLES
 399 --------------
 400
 401 Tracking and contributing to a the trunk of a Subversion-managed project:
 402
 403 ------------------------------------------------------------------------
 404 # Clone a repo (like git clone):
 405         git-svn clone http://svn.foo.org/project/trunk
 406 # Enter the newly cloned directory:
 407         cd trunk
 408 # You should be on master branch, double-check with git-branch
 409         git branch
 410 # Do some work and commit locally to git:
 411         git commit ...
 412 # Something is committed to SVN, rebase your local changes against the
 413 # latest changes in SVN:
 414         git-svn rebase
 415 # Now commit your changes (that were committed previously using git) to SVN,
 416 # as well as automatically updating your working HEAD:
 417         git-svn dcommit
 418 # Append svn:ignore settings to the default git exclude file:
 419         git-svn show-ignore >> .git/info/exclude
 420 ------------------------------------------------------------------------
 421
 422 Tracking and contributing to an entire Subversion-managed project
 423 (complete with a trunk, tags and branches):
 424
 425 ------------------------------------------------------------------------
 426 # Clone a repo (like git clone):
 427         git-svn clone http://svn.foo.org/project -T trunk -b branches -t tags
 428 # View all branches and tags you have cloned:
 429         git branch -r
 430 # Reset your master to trunk (or any other branch, replacing 'trunk'
 431 # with the appropriate name):
 432         git reset --hard remotes/trunk
 433 # You may only dcommit to one branch/tag/trunk at a time.  The usage
 434 # of dcommit/rebase/show-ignore should be the same as above.
 435 ------------------------------------------------------------------------
 436
 437 REBASE VS. PULL/MERGE
 438 ---------------------
 439
 440 Originally, git-svn recommended that the remotes/git-svn branch be
 441 pulled or merged from.  This is because the author favored
 442 'git-svn set-tree B' to commit a single head rather than the
 443 'git-svn set-tree A..B' notation to commit multiple commits.
 444
 445 If you use 'git-svn set-tree A..B' to commit several diffs and you do
 446 not have the latest remotes/git-svn merged into my-branch, you should
 447 use 'git-svn rebase' to update your work branch instead of 'git pull' or
 448 'git merge'.  'pull/merge' can cause non-linear history to be flattened
 449 when committing into SVN, which can lead to merge commits reversing
 450 previous commits in SVN.
 451
 452 DESIGN PHILOSOPHY
 453 -----------------
 454 Merge tracking in Subversion is lacking and doing branched development
 455 with Subversion is cumbersome as a result.  git-svn does not do
 456 automated merge/branch tracking by default and leaves it entirely up to
 457 the user on the git side.  git-svn does however follow copy
 458 history of the directory that it is tracking, however (much like
 459 how 'svn log' works).
 460
 461 BUGS
 462 ----
 463
 464 We ignore all SVN properties except svn:executable.  Any unhandled
 465 properties are logged to $GIT_DIR/svn/<refname>/unhandled.log
 466
 467 Renamed and copied directories are not detected by git and hence not
 468 tracked when committing to SVN.  I do not plan on adding support for
 469 this as it's quite difficult and time-consuming to get working for all
 470 the possible corner cases (git doesn't do it, either).  Committing
 471 renamed and copied files are fully supported if they're similar enough
 472 for git to detect them.
 473
 474 CONFIGURATION
 475 -------------
 476
 477 git-svn stores [svn-remote] configuration information in the
 478 repository .git/config file.  It is similar the core git
 479 [remote] sections except 'fetch' keys do not accept glob
 480 arguments; but they are instead handled by the 'branches'
 481 and 'tags' keys.  Since some SVN repositories are oddly
 482 configured with multiple projects glob expansions such those
 483 listed below are allowed:
 484
 485 ------------------------------------------------------------------------
 486 [svn-remote "project-a"]
 487         url = http://server.org/svn
 488         branches = branches/*/project-a:refs/remotes/project-a/branches/*
 489         tags = tags/*/project-a:refs/remotes/project-a/tags/*
 490         trunk = trunk/project-a:refs/remotes/project-a/trunk
 491 ------------------------------------------------------------------------
 492
 493 Keep in mind that the '*' (asterisk) wildcard of the local ref
 494 (left of the ':') *must* be the farthest right path component;
 495 however the remote wildcard may be anywhere as long as it's own
 496 independent path componet (surrounded by '/' or EOL).   This
 497 type of configuration is not automatically created by 'init' and
 498 should be manually entered with a text-editor or using
 499 gitlink:git-config[1]
 500
 501 SEE ALSO
 502 --------
 503 gitlink:git-rebase[1]
 504
 505 Author
 506 ------
 507 Written by Eric Wong <normalperson@yhbt.net>.
 508
 509 Documentation
 510 -------------
 511 Written by Eric Wong <normalperson@yhbt.net>.