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