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 a single Subversion
  15 branch and git. It is not to be confused with gitlink:git-svnimport[1].
  16 They were designed with very different goals in mind.
  17
  18 git-svn is 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.  git-svnimport is designed
  21 for read-only operation on repositories that match a particular layout
  22 (albeit the recommended one by SVN developers).
  23
  24 For importing svn, git-svnimport is potentially more powerful when
  25 operating on repositories organized under the recommended
  26 trunk/branch/tags structure, and should be faster, too.
  27
  28 git-svn mostly ignores the very limited view of branching that
  29 Subversion has.  This allows git-svn to be much easier to use,
  30 especially on repositories that are not organized in a manner that
  31 git-svnimport is designed for.
  32
  33 COMMANDS
  34 --------
  35 --
  36
  37 'init'::
  38         Creates an empty git repository with additional metadata
  39         directories for git-svn.  The Subversion URL must be specified
  40         as a command-line argument.
  41
  42 'fetch'::
  43
  44 Fetch unfetched revisions from the Subversion URL we are
  45 tracking.  refs/remotes/git-svn will be updated to the
  46 latest revision.
  47
  48 Note: You should never attempt to modify the remotes/git-svn
  49 branch outside of git-svn.  Instead, create a branch from
  50 remotes/git-svn and work on that branch.  Use the 'commit'
  51 command (see below) to write git commits back to
  52 remotes/git-svn.
  53
  54 See '<<fetch-args,Additional Fetch Arguments>>' if you are interested in
  55 manually joining branches on commit.
  56
  57 'commit'::
  58         Commit specified commit or tree objects to SVN.  This relies on
  59         your imported fetch data being up-to-date.  This makes
  60         absolutely no attempts to do patching when committing to SVN, it
  61         simply overwrites files with those specified in the tree or
  62         commit.  All merging is assumed to have taken place
  63         independently of git-svn functions.
  64
  65 'rebuild'::
  66         Not a part of daily usage, but this is a useful command if
  67         you've just cloned a repository (using gitlink:git-clone[1]) that was
  68         tracked with git-svn.  Unfortunately, git-clone does not clone
  69         git-svn metadata and the svn working tree that git-svn uses for
  70         its operations.  This rebuilds the metadata so git-svn can
  71         resume fetch operations.  A Subversion URL may be optionally
  72         specified at the command-line if the directory/repository you're
  73         tracking has moved or changed protocols.
  74
  75 'show-ignore'::
  76         Recursively finds and lists the svn:ignore property on
  77         directories.  The output is suitable for appending to
  78         the $GIT_DIR/info/exclude file.
  79
  80 --
  81
  82 OPTIONS
  83 -------
  84 --
  85
  86 -r <ARG>::
  87 --revision <ARG>::
  88
  89 Only used with the 'fetch' command.
  90
  91 Takes any valid -r<argument> svn would accept and passes it
  92 directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax
  93 is also supported.  This is passed directly to svn, see svn
  94 documentation for more details.
  95
  96 This can allow you to make partial mirrors when running fetch.
  97
  98 -::
  99 --stdin::
 100
 101 Only used with the 'commit' command.
 102
 103 Read a list of commits from stdin and commit them in reverse
 104 order.  Only the leading sha1 is read from each line, so
 105 git-rev-list --pretty=oneline output can be used.
 106
 107 --rmdir::
 108
 109 Only used with the 'commit' command.
 110
 111 Remove directories from the SVN tree if there are no files left
 112 behind.  SVN can version empty directories, and they are not
 113 removed by default if there are no files left in them.  git
 114 cannot version empty directories.  Enabling this flag will make
 115 the commit to SVN act like git.
 116
 117 repo-config key: svn.rmdir
 118
 119 -e::
 120 --edit::
 121
 122 Only used with the 'commit' command.
 123
 124 Edit the commit message before committing to SVN.  This is off by
 125 default for objects that are commits, and forced on when committing
 126 tree objects.
 127
 128 repo-config key: svn.edit
 129
 130 -l<num>::
 131 --find-copies-harder::
 132
 133 Both of these are only used with the 'commit' command.
 134
 135 They are both passed directly to git-diff-tree see
 136 gitlink:git-diff-tree[1] for more information.
 137
 138 [verse]
 139 repo-config key: svn.l
 140 repo-config key: svn.findcopiesharder
 141
 142 -A<filename>::
 143 --authors-file=<filename>::
 144
 145 Syntax is compatible with the files used by git-svnimport and
 146 git-cvsimport:
 147
 148 ------------------------------------------------------------------------
 149         loginname = Joe User <user@example.com>
 150 ------------------------------------------------------------------------
 151
 152 If this option is specified and git-svn encounters an SVN
 153 committer name that does not exist in the authors-file, git-svn
 154 will abort operation. The user will then have to add the
 155 appropriate entry.  Re-running the previous git-svn command
 156 after the authors-file is modified should continue operation.
 157
 158 repo-config key: svn.authors-file
 159
 160 --
 161
 162 ADVANCED OPTIONS
 163 ----------------
 164 --
 165
 166 -b<refname>::
 167 --branch <refname>::
 168 Used with 'fetch' or 'commit'.
 169
 170 This can be used to join arbitrary git branches to remotes/git-svn
 171 on new commits where the tree object is equivalent.
 172
 173 When used with different GIT_SVN_ID values, tags and branches in
 174 SVN can be tracked this way, as can some merges where the heads
 175 end up having completely equivalent content.  This can even be
 176 used to track branches across multiple SVN _repositories_.
 177
 178 This option may be specified multiple times, once for each
 179 branch.
 180
 181 repo-config key: svn.branch
 182
 183 -i<GIT_SVN_ID>::
 184 --id <GIT_SVN_ID>::
 185
 186 This sets GIT_SVN_ID (instead of using the environment).  See the
 187 section on
 188 '<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>'
 189 for more information on using GIT_SVN_ID.
 190
 191 --
 192
 193 COMPATIBILITY OPTIONS
 194 ---------------------
 195 --
 196
 197 --upgrade::
 198 Only used with the 'rebuild' command.
 199
 200 Run this if you used an old version of git-svn that used
 201 "git-svn-HEAD" instead of "remotes/git-svn" as the branch
 202 for tracking the remote.
 203
 204 --no-ignore-externals::
 205 Only used with the 'fetch' and 'rebuild' command.
 206
 207 By default, git-svn passes --ignore-externals to svn to avoid
 208 fetching svn:external trees into git.  Pass this flag to enable
 209 externals tracking directly via git.
 210
 211 Versions of svn that do not support --ignore-externals are
 212 automatically detected and this flag will be automatically
 213 enabled for them.
 214
 215 Otherwise, do not enable this flag unless you know what you're
 216 doing.
 217
 218 repo-config key: svn.noignoreexternals
 219
 220 --
 221
 222 Basic Examples
 223 ~~~~~~~~~~~~~~
 224
 225 Tracking and contributing to an Subversion managed-project:
 226
 227 ------------------------------------------------------------------------
 228 # Initialize a tree (like git init-db):
 229         git-svn init http://svn.foo.org/project/trunk
 230 # Fetch remote revisions:
 231         git-svn fetch
 232 # Create your own branch to hack on:
 233         git checkout -b my-branch remotes/git-svn
 234 # Commit only the git commits you want to SVN:
 235         git-svn commit <tree-ish> [<tree-ish_2> ...]
 236 # Commit all the git commits from my-branch that don't exist in SVN:
 237         git-svn commit remotes/git-svn..my-branch
 238 # Something is committed to SVN, rebase the latest into your branch:
 239         git-svn fetch && git rebase remotes/git-svn
 240 # Append svn:ignore settings to the default git exclude file:
 241         git-svn show-ignore >> .git/info/exclude
 242 ------------------------------------------------------------------------
 243
 244 REBASE VS. PULL
 245 ---------------
 246
 247 Originally, git-svn recommended that the remotes/git-svn branch be
 248 pulled from.  This is because the author favored 'git-svn commit B'
 249 to commit a single head rather than the 'git-svn commit A..B' notation
 250 to commit multiple commits.
 251
 252 If you use 'git-svn commit A..B' to commit several diffs and you do not
 253 have the latest remotes/git-svn merged into my-branch, you should use
 254 'git rebase' to update your work branch instead of 'git pull'.  'pull'
 255 can cause non-linear history to be flattened when committing into SVN,
 256 which can lead to merge commits reversing previous commits in SVN.
 257
 258 DESIGN PHILOSOPHY
 259 -----------------
 260 Merge tracking in Subversion is lacking and doing branched development
 261 with Subversion is cumbersome as a result.  git-svn completely forgoes
 262 any automated merge/branch tracking on the Subversion side and leaves it
 263 entirely up to the user on the git side.  It's simply not worth it to do
 264 a useful translation when the original signal is weak.
 265
 266 [[tracking-multiple-repos]]
 267 TRACKING MULTIPLE REPOSITORIES OR BRANCHES
 268 ------------------------------------------
 269 This is for advanced users, most users should ignore this section.
 270
 271 Because git-svn does not care about relationships between different
 272 branches or directories in a Subversion repository, git-svn has a simple
 273 hack to allow it to track an arbitrary number of related _or_ unrelated
 274 SVN repositories via one git repository.  Simply set the GIT_SVN_ID
 275 environment variable to a name other other than "git-svn" (the default)
 276 and git-svn will ignore the contents of the $GIT_DIR/git-svn directory
 277 and instead do all of its work in $GIT_DIR/$GIT_SVN_ID for that
 278 invocation.  The interface branch will be remotes/$GIT_SVN_ID, instead of
 279 remotes/git-svn.  Any remotes/$GIT_SVN_ID branch should never be modified
 280 by the user outside of git-svn commands.
 281
 282 [[fetch-args]]
 283 ADDITIONAL FETCH ARGUMENTS
 284 --------------------------
 285 This is for advanced users, most users should ignore this section.
 286
 287 Unfetched SVN revisions may be imported as children of existing commits
 288 by specifying additional arguments to 'fetch'.  Additional parents may
 289 optionally be specified in the form of sha1 hex sums at the
 290 command-line.  Unfetched SVN revisions may also be tied to particular
 291 git commits with the following syntax:
 292
 293 ------------------------------------------------
 294         svn_revision_number=git_commit_sha1
 295 ------------------------------------------------
 296
 297 This allows you to tie unfetched SVN revision 375 to your current HEAD:
 298
 299 ------------------------------------------------
 300         git-svn fetch 375=$(git-rev-parse HEAD)
 301 ------------------------------------------------
 302
 303 Advanced Example: Tracking a Reorganized Repository
 304 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 305 If you're tracking a directory that has moved, or otherwise been
 306 branched or tagged off of another directory in the repository and you
 307 care about the full history of the project, then you can read this
 308 section.
 309
 310 This is how Yann Dirson tracked the trunk of the ufoai directory when
 311 the /trunk directory of his repository was moved to /ufoai/trunk and
 312 he needed to continue tracking /ufoai/trunk where /trunk left off.
 313
 314 ------------------------------------------------------------------------
 315         # This log message shows when the repository was reorganized:
 316         r166 | ydirson | 2006-03-02 01:36:55 +0100 (Thu, 02 Mar 2006) | 1 line
 317         Changed paths:
 318            D /trunk
 319            A /ufoai/trunk (from /trunk:165)
 320
 321         # First we start tracking the old revisions:
 322         GIT_SVN_ID=git-oldsvn git-svn init \
 323                         https://svn.sourceforge.net/svnroot/ufoai/trunk
 324         GIT_SVN_ID=git-oldsvn git-svn fetch -r1:165
 325
 326         # And now, we continue tracking the new revisions:
 327         GIT_SVN_ID=git-newsvn git-svn init \
 328               https://svn.sourceforge.net/svnroot/ufoai/ufoai/trunk
 329         GIT_SVN_ID=git-newsvn git-svn fetch \
 330               166=`git-rev-parse refs/remotes/git-oldsvn`
 331 ------------------------------------------------------------------------
 332
 333 BUGS
 334 ----
 335 If somebody commits a conflicting changeset to SVN at a bad moment
 336 (right before you commit) causing a conflict and your commit to fail,
 337 your svn working tree ($GIT_DIR/git-svn/tree) may be dirtied.  The
 338 easiest thing to do is probably just to rm -rf $GIT_DIR/git-svn/tree and
 339 run 'rebuild'.
 340
 341 We ignore all SVN properties except svn:executable.  Too difficult to
 342 map them since we rely heavily on git write-tree being _exactly_ the
 343 same on both the SVN and git working trees and I prefer not to clutter
 344 working trees with metadata files.
 345
 346 svn:keywords can't be ignored in Subversion (at least I don't know of
 347 a way to ignore them).
 348
 349 Renamed and copied directories are not detected by git and hence not
 350 tracked when committing to SVN.  I do not plan on adding support for
 351 this as it's quite difficult and time-consuming to get working for all
 352 the possible corner cases (git doesn't do it, either).  Renamed and
 353 copied files are fully supported if they're similar enough for git to
 354 detect them.
 355
 356 SEE ALSO
 357 --------
 358 gitlink:git-rebase[1]
 359
 360 Author
 361 ------
 362 Written by Eric Wong <normalperson@yhbt.net>.
 363
 364 Documentation
 365 -------------
 366 Written by Eric Wong <normalperson@yhbt.net>.