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