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