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