Fix typos in the documentation
[git/git.git] / Documentation / git-svn.txt
CommitLineData
3397f9df
EW
1git-svn(1)
2==========
3
4NAME
5----
ab81a364 6git-svn - Bidirectional operation between a Subversion repository and git
3397f9df
EW
7
8SYNOPSIS
9--------
b1889c36 10'git svn' <command> [options] [arguments]
3397f9df
EW
11
12DESCRIPTION
13-----------
647ac702 14'git svn' is a simple conduit for changesets between Subversion and git.
8cb070a4 15It provides a bidirectional flow of changes between a Subversion and a git
1168d402 16repository.
3397f9df 17
647ac702 18'git svn' can track a standard Subversion repository,
ab81a364
MB
19following the common "trunk/branches/tags" layout, with the --stdlayout option.
20It can also follow branches and tags in any layout with the -T/-t/-b options
21(see options to 'init' below, and also the 'clone' command).
3397f9df 22
ab81a364 23Once tracking a Subversion repository (with any of the above methods), the git
8cb070a4
BG
24repository can be updated from Subversion by the 'fetch' command and
25Subversion updated from git by the 'dcommit' command.
3397f9df
EW
26
27COMMANDS
28--------
0ea4d4c9
JF
29
30'init'::
a836a0e1 31 Initializes an empty git repository with additional
647ac702 32 metadata directories for 'git svn'. The Subversion URL
a836a0e1
EW
33 may be specified as a command-line argument, or as full
34 URL arguments to -T/-t/-b. Optionally, the target
35 directory to operate on can be specified as a second
36 argument. Normally this command initializes the current
37 directory.
3397f9df 38
cc1793e2
KW
39-T<trunk_subdir>;;
40--trunk=<trunk_subdir>;;
41-t<tags_subdir>;;
42--tags=<tags_subdir>;;
43-b<branches_subdir>;;
44--branches=<branches_subdir>;;
8f728fb9 45-s;;
46--stdlayout;;
a836a0e1
EW
47 These are optional command-line options for init. Each of
48 these flags can point to a relative repository path
ab81a364
MB
49 (--tags=project/tags) or a full url
50 (--tags=https://foo.org/project/tags).
51 You can specify more than one --tags and/or --branches options, in case
52 your Subversion repository places tags or branches under multiple paths.
53 The option --stdlayout is
8f728fb9 54 a shorthand way of setting trunk,tags,branches as the relative paths,
55 which is the Subversion default. If any of the other options are given
56 as well, they take precedence.
cc1793e2 57--no-metadata;;
0dfaf0a4 58 Set the 'noMetadata' option in the [svn-remote] config.
c9be27f3
EW
59 This option is not recommended, please read the 'svn.noMetadata'
60 section of this manpage before using this option.
cc1793e2 61--use-svm-props;;
0dfaf0a4 62 Set the 'useSvmProps' option in the [svn-remote] config.
cc1793e2 63--use-svnsync-props;;
0dfaf0a4 64 Set the 'useSvnsyncProps' option in the [svn-remote] config.
cc1793e2 65--rewrite-root=<URL>;;
0dfaf0a4 66 Set the 'rewriteRoot' option in the [svn-remote] config.
3e18ce1a
JS
67--rewrite-uuid=<UUID>;;
68 Set the 'rewriteUUID' option in the [svn-remote] config.
cc1793e2 69--username=<USER>;;
a0d7fe3f
SV
70 For transports that SVN handles authentication for (http,
71 https, and plain svn), specify the username. For other
72 transports (eg svn+ssh://), you must include the username in
73 the URL, eg svn+ssh://foo@svn.bar.com/project
cc1793e2 74--prefix=<prefix>;;
a836a0e1
EW
75 This allows one to specify a prefix which is prepended
76 to the names of remotes if trunk/branches/tags are
77 specified. The prefix does not automatically include a
78 trailing slash, so be sure you include one in the
0d351e9c
GP
79 argument if that is what you want. If --branches/-b is
80 specified, the prefix must include a trailing slash.
81 Setting a prefix is useful if you wish to track multiple
82 projects that share a common repository.
88ec2054
BJ
83--ignore-paths=<regex>;;
84 When passed to 'init' or 'clone' this regular expression will
85 be preserved as a config key. See 'fetch' for a description
86 of '--ignore-paths'.
6b48829d
EW
87--no-minimize-url;;
88 When tracking multiple directories (using --stdlayout,
89 --branches, or --tags options), git svn will attempt to connect
90 to the root (or highest allowed level) of the Subversion
91 repository. This default allows better tracking of history if
92 entire projects are moved within a repository, but may cause
93 issues on repositories where read access restrictions are in
94 place. Passing '--no-minimize-url' will allow git svn to
95 accept URLs as-is without attempting to connect to a higher
96 level directory. This option is off by default when only
97 one URL/branch is tracked (it would do little good).
81c5a0e6 98
a836a0e1 99'fetch'::
a836a0e1
EW
100 Fetch unfetched revisions from the Subversion remote we are
101 tracking. The name of the [svn-remote "..."] section in the
102 .git/config file may be specified as an optional command-line
103 argument.
b705ba43 104
e82f0d73
PH
105--localtime;;
106 Store Git commit times in the local timezone instead of UTC. This
647ac702 107 makes 'git log' (even without --date=local) show the same times
e82f0d73 108 that `svn log` would in the local timezone.
6c32a7a9 109+
e82f0d73
PH
110This doesn't interfere with interoperating with the Subversion
111repository you cloned from, but if you wish for your local Git
112repository to be able to interoperate with someone else's local Git
113repository, either don't use this option or you should both use it in
114the same local timezone.
115
61f36a79
TS
116--parent;;
117 Fetch only from the SVN parent of the current HEAD.
118
6076b843 119--ignore-paths=<regex>;;
0d8bee71 120 This allows one to specify a Perl regular expression that will
6076b843 121 cause skipping of all matching paths from checkout from SVN.
0d8bee71
BJ
122 The '--ignore-paths' option should match for every 'fetch'
123 (including automatic fetches due to 'clone', 'dcommit',
124 'rebase', etc) on a given repository.
6c32a7a9
YD
125+
126[verse]
0d8bee71 127config key: svn-remote.<name>.ignore-paths
6c32a7a9
YD
128+
129If the ignore-paths config key is set and the command line option is
130also given, both regular expressions will be used.
131+
0d8bee71 132Examples:
6c32a7a9
YD
133+
134--
135Skip "doc*" directory for every fetch;;
136+
137------------------------------------------------------------------------
138--ignore-paths="^doc"
139------------------------------------------------------------------------
0d8bee71 140
6c32a7a9
YD
141Skip "branches" and "tags" of first level directories;;
142+
143------------------------------------------------------------------------
144--ignore-paths="^[^/]+/(?:branches|tags)"
145------------------------------------------------------------------------
146--
6076b843 147
eb1f7e0d
YD
148--use-log-author;;
149 When retrieving svn commits into git (as part of fetch, rebase, or
150 dcommit operations), look for the first From: or Signed-off-by: line
151 in the log message and use that as the author string.
152--add-author-from;;
153 When committing to svn from git (as part of commit or dcommit
154 operations), if the existing log message doesn't already have a
155 From: or Signed-off-by: line, append a From: line based on the
156 git commit's author string. If you use this, then --use-log-author
157 will retrieve a valid author string for all commits.
158
a81ed0b6
EW
159'clone'::
160 Runs 'init' and 'fetch'. It will automatically create a
161 directory based on the basename of the URL passed to it;
162 or if a second argument is passed; it will create a directory
163 and work within that. It accepts all arguments that the
164 'init' and 'fetch' commands accept; with the exception of
0da3e1d2
YD
165 '--fetch-all' and '--parent'. After a repository is cloned,
166 the 'fetch' command will be able to update revisions without
167 affecting the working tree; and the 'rebase' command will be
168 able to update the working tree with the latest changes.
a81ed0b6
EW
169
170'rebase'::
171 This fetches revisions from the SVN parent of the current HEAD
172 and rebases the current (uncommitted to SVN) work against it.
6c32a7a9 173+
647ac702
YD
174This works similarly to `svn update` or 'git pull' except that
175it preserves linear history with 'git rebase' instead of
176'git merge' for ease of dcommitting with 'git svn'.
6c32a7a9 177+
647ac702 178This accepts all options that 'git svn fetch' and 'git rebase'
483bc4f0 179accept. However, '--fetch-all' only fetches from the current
112f6385 180[svn-remote], and not all [svn-remote] definitions.
6c32a7a9 181+
647ac702 182Like 'git rebase'; this requires that the working tree be clean
112f6385 183and have no uncommitted changes.
cc1793e2 184
dee41f3e
EW
185-l;;
186--local;;
647ac702 187 Do not fetch remotely; only run 'git rebase' against the
dee41f3e 188 last fetched commit from the upstream SVN.
a81ed0b6 189
b22d4497 190'dcommit'::
2eff1425 191 Commit each diff from a specified head directly to the SVN
b22d4497 192 repository, and then rebase or reset (depending on whether or
2eff1425
EW
193 not there is a diff between SVN and head). This will create
194 a revision in SVN for each commit in git.
647ac702 195 It is recommended that you run 'git svn' fetch and rebase (not
2eff1425
EW
196 pull or merge) your commits against the latest changes in the
197 SVN repository.
5eec27e3 198 An optional revision or branch argument may be specified, and
647ac702 199 causes 'git svn' to do all work on that revision/branch
5eec27e3 200 instead of HEAD.
3289e86e 201 This is advantageous over 'set-tree' (below) because it produces
b22d4497 202 cleaner, more linear history.
171af110
KW
203+
204--no-rebase;;
205 After committing, do not rebase or reset.
ba24e745
EW
206--commit-url <URL>;;
207 Commit to this SVN URL (the full path). This is intended to
647ac702 208 allow existing 'git svn' repositories created with one transport
ba24e745
EW
209 method (e.g. `svn://` or `http://` for anonymous read) to be
210 reused if a user is later given access to an alternate transport
211 method (e.g. `svn+ssh://` or `https://`) for commit.
6c32a7a9
YD
212+
213[verse]
0df84059 214config key: svn-remote.<name>.commiturl
0df84059 215config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options)
6c32a7a9
YD
216+
217Using this option for any other purpose (don't ask) is very strongly
218discouraged.
b22d4497 219
5de70efb
FR
220'branch'::
221 Create a branch in the SVN repository.
222
223-m;;
224--message;;
225 Allows to specify the commit message.
226
227-t;;
228--tag;;
229 Create a tag by using the tags_subdir instead of the branches_subdir
230 specified during git svn init.
231
ab81a364
MB
232-d;;
233--destination;;
234 If more than one --branches (or --tags) option was given to the 'init'
235 or 'clone' command, you must provide the location of the branch (or
236 tag) you wish to create in the SVN repository. The value of this
237 option must match one of the paths specified by a --branches (or
238 --tags) option. You can see these paths with the commands
239+
240 git config --get-all svn-remote.<name>.branches
241 git config --get-all svn-remote.<name>.tags
242+
243where <name> is the name of the SVN repository as specified by the -R option to
244'init' (or "svn" by default).
245
a65f3c20
IM
246--username;;
247 Specify the SVN username to perform the commit as. This option overrides
cb82dbf8 248 the 'username' configuration property.
a65f3c20
IM
249
250--commit-url;;
251 Use the specified URL to connect to the destination Subversion
252 repository. This is useful in cases where the source SVN
253 repository is read-only. This option overrides configuration
254 property 'commiturl'.
255+
256 git config --get-all svn-remote.<name>.commiturl
257+
258
5de70efb
FR
259'tag'::
260 Create a tag in the SVN repository. This is a shorthand for
261 'branch -t'.
262
e8f5d908
EW
263'log'::
264 This should make it easy to look up svn log messages when svn
265 users refer to -r/--revision numbers.
112f6385
SV
266+
267The following features from `svn log' are supported:
268+
269--
6c32a7a9
YD
270-r <n>[:<n>];;
271--revision=<n>[:<n>];;
112f6385
SV
272 is supported, non-numeric args are not:
273 HEAD, NEXT, BASE, PREV, etc ...
6c32a7a9
YD
274-v;;
275--verbose;;
112f6385
SV
276 it's not completely compatible with the --verbose
277 output in svn log, but reasonably close.
278--limit=<n>;;
279 is NOT the same as --max-count, doesn't count
280 merged/excluded commits
281--incremental;;
282 supported
283--
284+
285New features:
286+
287--
288--show-commit;;
289 shows the git commit sha1, as well
290--oneline;;
291 our version of --pretty=oneline
292--
293+
a50a5c8f
MV
294NOTE: SVN itself only stores times in UTC and nothing else. The regular svn
295client converts the UTC time to the local time (or based on the TZ=
296environment). This command has the same behaviour.
297+
647ac702 298Any other arguments are passed directly to 'git log'
e8f5d908 299
6fb5375e 300'blame'::
4be40381
SG
301 Show what revision and author last modified each line of a file. The
302 output of this mode is format-compatible with the output of
303 `svn blame' by default. Like the SVN blame command,
304 local uncommitted changes in the working copy are ignored;
305 the version of the file in the HEAD revision is annotated. Unknown
647ac702 306 arguments are passed directly to 'git blame'.
6fb5375e 307+
4be40381 308--git-format;;
647ac702 309 Produce output in the same format as 'git blame', but with
4be40381
SG
310 SVN revision numbers instead of git commit hashes. In this mode,
311 changes that haven't been committed to SVN (including local
312 working-copy edits) are shown as revision 0.
6fb5375e 313
26e60160
AR
314'find-rev'::
315 When given an SVN revision number of the form 'rN', returns the
b3cb7e45
AR
316 corresponding git commit hash (this can optionally be followed by a
317 tree-ish to specify which branch should be searched). When given a
318 tree-ish, returns the corresponding SVN revision number.
26e60160 319
3289e86e 320'set-tree'::
e8f5d908 321 You should consider using 'dcommit' instead of this command.
3397f9df
EW
322 Commit specified commit or tree objects to SVN. This relies on
323 your imported fetch data being up-to-date. This makes
324 absolutely no attempts to do patching when committing to SVN, it
325 simply overwrites files with those specified in the tree or
326 commit. All merging is assumed to have taken place
647ac702 327 independently of 'git svn' functions.
3397f9df 328
da060c67 329'create-ignore'::
da060c67
GH
330 Recursively finds the svn:ignore property on directories and
331 creates matching .gitignore files. The resulting files are staged to
69239728 332 be committed, but are not committed. Use -r/--revision to refer to a
1168d402 333 specific revision.
da060c67 334
0ea4d4c9 335'show-ignore'::
8f22562c
EW
336 Recursively finds and lists the svn:ignore property on
337 directories. The output is suitable for appending to
338 the $GIT_DIR/info/exclude file.
339
6111b934
EW
340'mkdirs'::
341 Attempts to recreate empty directories that core git cannot track
342 based on information in $GIT_DIR/svn/<refname>/unhandled.log files.
343 Empty directories are automatically recreated when using
344 "git svn clone" and "git svn rebase", so "mkdirs" is intended
345 for use after commands like "git checkout" or "git reset".
346
e8f5d908
EW
347'commit-diff'::
348 Commits the diff of two tree-ish arguments from the
647ac702 349 command-line. This command does not rely on being inside an `git svn
483bc4f0 350 init`-ed repository. This command takes three arguments, (a) the
e8f5d908
EW
351 original tree to diff against, (b) the new tree result, (c) the
352 URL of the target Subversion repository. The final argument
647ac702
YD
353 (URL) may be omitted if you are working from a 'git svn'-aware
354 repository (that has been `init`-ed with 'git svn').
45bf473a 355 The -r<revision> option is required for this.
e8f5d908 356
e6fefa92
DK
357'info'::
358 Shows information about a file or directory similar to what
359 `svn info' provides. Does not currently support a -r/--revision
8b014d71
DK
360 argument. Use the --url option to output only the value of the
361 'URL:' field.
e6fefa92 362
69239728
GH
363'proplist'::
364 Lists the properties stored in the Subversion repository about a
365 given file or directory. Use -r/--revision to refer to a specific
366 Subversion revision.
367
368'propget'::
369 Gets the Subversion property given as the first argument, for a
370 file. A specific revision can be specified with -r/--revision.
371
372'show-externals'::
373 Shows the Subversion externals. Use -r/--revision to specify a
374 specific revision.
375
2da9ee08
RZ
376'gc'::
377 Compress $GIT_DIR/svn/<refname>/unhandled.log files in .git/svn
378 and remove $GIT_DIR/svn/<refname>index files in .git/svn.
379
195643f2
BJ
380'reset'::
381 Undoes the effects of 'fetch' back to the specified revision.
382 This allows you to re-'fetch' an SVN revision. Normally the
383 contents of an SVN revision should never change and 'reset'
384 should not be necessary. However, if SVN permissions change,
385 or if you alter your --ignore-paths option, a 'fetch' may fail
386 with "not found in commit" (file not previously visible) or
387 "checksum mismatch" (missed a modification). If the problem
388 file cannot be ignored forever (with --ignore-paths) the only
389 way to repair the repo is to use 'reset'.
6c32a7a9 390+
195643f2 391Only the rev_map and refs/remotes/git-svn are changed. Follow 'reset'
647ac702 392with a 'fetch' and then 'git reset' or 'git rebase' to move local
195643f2
BJ
393branches onto the new tree.
394
6c32a7a9
YD
395-r <n>;;
396--revision=<n>;;
195643f2
BJ
397 Specify the most recent revision to keep. All later revisions
398 are discarded.
6c32a7a9
YD
399-p;;
400--parent;;
195643f2
BJ
401 Discard the specified revision as well, keeping the nearest
402 parent instead.
403Example:;;
404Assume you have local changes in "master", but you need to refetch "r2".
6c32a7a9 405+
195643f2
BJ
406------------
407 r1---r2---r3 remotes/git-svn
408 \
409 A---B master
410------------
6c32a7a9 411+
195643f2
BJ
412Fix the ignore-paths or SVN permissions problem that caused "r2" to
413be incomplete in the first place. Then:
6c32a7a9 414+
195643f2
BJ
415[verse]
416git svn reset -r2 -p
417git svn fetch
6c32a7a9 418+
195643f2
BJ
419------------
420 r1---r2'--r3' remotes/git-svn
421 \
422 r2---r3---A---B master
423------------
6c32a7a9 424+
647ac702
YD
425Then fixup "master" with 'git rebase'.
426Do NOT use 'git merge' or your history will not be compatible with a
195643f2 427future 'dcommit'!
6c32a7a9 428+
195643f2
BJ
429[verse]
430git rebase --onto remotes/git-svn A^ master
6c32a7a9 431+
195643f2
BJ
432------------
433 r1---r2'--r3' remotes/git-svn
434 \
435 A'--B' master
436------------
437
3397f9df
EW
438OPTIONS
439-------
0ea4d4c9 440
0adda936 441--shared[=(false|true|umask|group|all|world|everybody)]::
e8f5d908
EW
442--template=<template_directory>::
443 Only used with the 'init' command.
647ac702 444 These are passed directly to 'git init'.
e8f5d908 445
3397f9df
EW
446-r <ARG>::
447--revision <ARG>::
6c32a7a9
YD
448 Used with the 'fetch' command.
449+
a836a0e1
EW
450This allows revision ranges for partial/cauterized history
451to be supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges),
452$NUMBER:HEAD, and BASE:$NUMBER are all supported.
6c32a7a9 453+
a836a0e1
EW
454This can allow you to make partial mirrors when running fetch;
455but is generally not recommended because history will be skipped
456and lost.
3397f9df
EW
457
458-::
459--stdin::
6c32a7a9
YD
460 Only used with the 'set-tree' command.
461+
0ea4d4c9
JF
462Read a list of commits from stdin and commit them in reverse
463order. Only the leading sha1 is read from each line, so
647ac702 464'git rev-list --pretty=oneline' output can be used.
3397f9df
EW
465
466--rmdir::
6c32a7a9
YD
467 Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
468+
0ea4d4c9
JF
469Remove directories from the SVN tree if there are no files left
470behind. SVN can version empty directories, and they are not
471removed by default if there are no files left in them. git
472cannot version empty directories. Enabling this flag will make
473the commit to SVN act like git.
6c32a7a9
YD
474+
475[verse]
e0d10e1c 476config key: svn.rmdir
20b1d700 477
3397f9df
EW
478-e::
479--edit::
6c32a7a9
YD
480 Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
481+
0ea4d4c9
JF
482Edit the commit message before committing to SVN. This is off by
483default for objects that are commits, and forced on when committing
484tree objects.
6c32a7a9
YD
485+
486[verse]
e0d10e1c 487config key: svn.edit
20b1d700 488
72942938
EW
489-l<num>::
490--find-copies-harder::
6c32a7a9
YD
491 Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
492+
647ac702 493They are both passed directly to 'git diff-tree'; see
5162e697 494linkgit:git-diff-tree[1] for more information.
6c32a7a9 495+
0ea4d4c9 496[verse]
e0d10e1c
TP
497config key: svn.l
498config key: svn.findcopiesharder
20b1d700 499
81c5a0e6
EW
500-A<filename>::
501--authors-file=<filename>::
6c32a7a9
YD
502 Syntax is compatible with the file used by 'git cvsimport':
503+
81c5a0e6 504------------------------------------------------------------------------
0ea4d4c9 505 loginname = Joe User <user@example.com>
81c5a0e6 506------------------------------------------------------------------------
6c32a7a9 507+
647ac702
YD
508If this option is specified and 'git svn' encounters an SVN
509committer name that does not exist in the authors-file, 'git svn'
0ea4d4c9 510will abort operation. The user will then have to add the
647ac702 511appropriate entry. Re-running the previous 'git svn' command
0ea4d4c9 512after the authors-file is modified should continue operation.
6c32a7a9
YD
513+
514[verse]
e0d10e1c 515config key: svn.authorsfile
e8f5d908 516
36db1edd 517--authors-prog=<filename>::
6c32a7a9
YD
518 If this option is specified, for each SVN committer name that
519 does not exist in the authors file, the given file is executed
520 with the committer name as the first argument. The program is
521 expected to return a single line of the form "Name <email>",
522 which will be treated as if included in the authors file.
36db1edd 523
e8f5d908
EW
524-q::
525--quiet::
647ac702 526 Make 'git svn' less verbose. Specify a second time to make it
49750f30 527 even less verbose.
e8f5d908
EW
528
529--repack[=<n>]::
112f6385 530--repack-flags=<flags>::
6c32a7a9
YD
531 These should help keep disk usage sane for large fetches with
532 many revisions.
533+
112f6385
SV
534--repack takes an optional argument for the number of revisions
535to fetch before repacking. This defaults to repacking every
5361000 commits fetched if no argument is specified.
6c32a7a9 537+
647ac702 538--repack-flags are passed directly to 'git repack'.
6c32a7a9 539+
112f6385 540[verse]
e0d10e1c
TP
541config key: svn.repack
542config key: svn.repackflags
0ea4d4c9 543
b22d4497
EW
544-m::
545--merge::
546-s<strategy>::
547--strategy=<strategy>::
6c32a7a9
YD
548 These are only used with the 'dcommit' and 'rebase' commands.
549+
647ac702
YD
550Passed directly to 'git rebase' when using 'dcommit' if a
551'git reset' cannot be used (see 'dcommit').
b22d4497
EW
552
553-n::
554--dry-run::
6c32a7a9
YD
555 This can be used with the 'dcommit', 'rebase', 'branch' and
556 'tag' commands.
557+
7d45e146 558For 'dcommit', print out the series of git arguments that would show
b22d4497 559which diffs would be committed to SVN.
6c32a7a9 560+
7d45e146
SF
561For 'rebase', display the local branch associated with the upstream svn
562repository associated with the current branch and the URL of svn
563repository that will be fetched from.
6c32a7a9 564+
5de70efb
FR
565For 'branch' and 'tag', display the urls that will be used for copying when
566creating the branch or tag.
567
81c5a0e6 568
448c81b4
EW
569ADVANCED OPTIONS
570----------------
0ea4d4c9 571
448c81b4
EW
572-i<GIT_SVN_ID>::
573--id <GIT_SVN_ID>::
6c32a7a9
YD
574 This sets GIT_SVN_ID (instead of using the environment). This
575 allows the user to override the default refname to fetch from
576 when tracking a single URL. The 'log' and 'dcommit' commands
577 no longer require this switch as an argument.
0ea4d4c9 578
9760adcc
EW
579-R<remote name>::
580--svn-remote <remote name>::
581 Specify the [svn-remote "<remote name>"] section to use,
a836a0e1
EW
582 this allows SVN multiple repositories to be tracked.
583 Default: "svn"
9760adcc 584
e8f5d908
EW
585--follow-parent::
586 This is especially helpful when we're tracking a directory
587 that has been moved around within the repository, or if we
588 started tracking a branch and never tracked the trunk it was
0bed5eaa
EW
589 descended from. This feature is enabled by default, use
590 --no-follow-parent to disable it.
6c32a7a9
YD
591+
592[verse]
e0d10e1c 593config key: svn.followparent
e8f5d908 594
a81ed0b6
EW
595CONFIG FILE-ONLY OPTIONS
596------------------------
a81ed0b6 597
0dfaf0a4
EW
598svn.noMetadata::
599svn-remote.<name>.noMetadata::
6c32a7a9
YD
600 This gets rid of the 'git-svn-id:' lines at the end of every commit.
601+
c9be27f3
EW
602This option can only be used for one-shot imports as 'git svn'
603will not be able to fetch again without metadata. Additionally,
604if you lose your .git/svn/**/.rev_map.* files, 'git svn' will not
605be able to rebuild them.
6c32a7a9 606+
647ac702 607The 'git svn log' command will not work on repositories using
112f6385
SV
608this, either. Using this conflicts with the 'useSvmProps'
609option for (hopefully) obvious reasons.
c9be27f3
EW
610+
611This option is NOT recommended as it makes it difficult to track down
612old references to SVN revision numbers in existing documentation, bug
613reports and archives. If you plan to eventually migrate from SVN to git
614and are certain about dropping SVN history, consider
615linkgit:git-filter-branch[1] instead. filter-branch also allows
469bfc96 616reformatting of metadata for ease-of-reading and rewriting authorship
c9be27f3 617info for non-"svn.authorsFile" users.
97ae0911 618
0dfaf0a4
EW
619svn.useSvmProps::
620svn-remote.<name>.useSvmProps::
6c32a7a9
YD
621 This allows 'git svn' to re-map repository URLs and UUIDs from
622 mirrors created using SVN::Mirror (or svk) for metadata.
623+
112f6385
SV
624If an SVN revision has a property, "svm:headrev", it is likely
625that the revision was created by SVN::Mirror (also used by SVK).
626The property contains a repository UUID and a revision. We want
627to make it look like we are mirroring the original URL, so
628introduce a helper function that returns the original identity
629URL and UUID, and use it when generating metadata in commit
630messages.
97ae0911 631
0dfaf0a4
EW
632svn.useSvnsyncProps::
633svn-remote.<name>.useSvnsyncprops::
a81ed0b6
EW
634 Similar to the useSvmProps option; this is for users
635 of the svnsync(1) command distributed with SVN 1.4.x and
636 later.
637
0dfaf0a4 638svn-remote.<name>.rewriteRoot::
a81ed0b6 639 This allows users to create repositories from alternate
647ac702 640 URLs. For example, an administrator could run 'git svn' on the
a81ed0b6
EW
641 server locally (accessing via file://) but wish to distribute
642 the repository with a public http:// or svn:// URL in the
643 metadata so users of it will see the public URL.
644
3e18ce1a
JS
645svn-remote.<name>.rewriteUUID::
646 Similar to the useSvmProps option; this is for users who need
647 to remap the UUID manually. This may be useful in situations
648 where the original UUID is not available via either useSvmProps
649 or useSvnsyncProps.
650
4c58a711 651svn.brokenSymlinkWorkaround::
6c32a7a9
YD
652 This disables potentially expensive checks to workaround
653 broken symlinks checked into SVN by broken clients. Set this
654 option to "false" if you track a SVN repository with many
655 empty blobs that are not symlinks. This option may be changed
656 while 'git svn' is running and take effect on the next
657 revision fetched. If unset, 'git svn' assumes this option to
658 be "true".
3b2bbe9b 659
3713e222
DS
660svn.pathnameencoding::
661 This instructs git svn to recode pathnames to a given encoding.
662 It can be used by windows users and by those who work in non-utf8
663 locales to avoid corrupted file names with non-ASCII characters.
664 Valid encodings are the ones supported by Perl's Encode module.
665
3e18ce1a 666Since the noMetadata, rewriteRoot, rewriteUUID, useSvnsyncProps and useSvmProps
647ac702 667options all affect the metadata generated and used by 'git svn'; they
a81ed0b6
EW
668*must* be set in the configuration file before any history is imported
669and these settings should never be changed once they are set.
670
3e18ce1a
JS
671Additionally, only one of these options can be used per svn-remote
672section because they affect the 'git-svn-id:' metadata line, except
673for rewriteRoot and rewriteUUID which can be used together.
e8f5d908 674
448c81b4 675
112f6385
SV
676BASIC EXAMPLES
677--------------
3397f9df 678
06ada152 679Tracking and contributing to the trunk of a Subversion-managed project:
3397f9df 680
20b1d700 681------------------------------------------------------------------------
a81ed0b6 682# Clone a repo (like git clone):
2670ddce 683 git svn clone http://svn.example.com/project/trunk
a81ed0b6
EW
684# Enter the newly cloned directory:
685 cd trunk
647ac702 686# You should be on master branch, double-check with 'git branch'
a81ed0b6
EW
687 git branch
688# Do some work and commit locally to git:
689 git commit ...
690# Something is committed to SVN, rebase your local changes against the
691# latest changes in SVN:
b1889c36 692 git svn rebase
a81ed0b6
EW
693# Now commit your changes (that were committed previously using git) to SVN,
694# as well as automatically updating your working HEAD:
b1889c36 695 git svn dcommit
20b1d700 696# Append svn:ignore settings to the default git exclude file:
b1889c36 697 git svn show-ignore >> .git/info/exclude
20b1d700 698------------------------------------------------------------------------
3397f9df 699
0d313b2b
EW
700Tracking and contributing to an entire Subversion-managed project
701(complete with a trunk, tags and branches):
0d313b2b
EW
702
703------------------------------------------------------------------------
a81ed0b6 704# Clone a repo (like git clone):
2670ddce 705 git svn clone http://svn.example.com/project -T trunk -b branches -t tags
a81ed0b6
EW
706# View all branches and tags you have cloned:
707 git branch -r
5de70efb
FR
708# Create a new branch in SVN
709 git svn branch waldo
a81ed0b6
EW
710# Reset your master to trunk (or any other branch, replacing 'trunk'
711# with the appropriate name):
712 git reset --hard remotes/trunk
713# You may only dcommit to one branch/tag/trunk at a time. The usage
20f50f16 714# of dcommit/rebase/show-ignore should be the same as above.
0d313b2b
EW
715------------------------------------------------------------------------
716
647ac702 717The initial 'git svn clone' can be quite time-consuming
7d4aef40
AR
718(especially for large Subversion repositories). If multiple
719people (or one person with multiple machines) want to use
647ac702
YD
720'git svn' to interact with the same Subversion repository, you can
721do the initial 'git svn clone' to a repository on a server and
722have each person clone that repository with 'git clone':
7d4aef40
AR
723
724------------------------------------------------------------------------
725# Do the initial import on a server
2670ddce 726 ssh server "cd /pub && git svn clone http://svn.example.com/project
2b0d1033
SV
727# Clone locally - make sure the refs/remotes/ space matches the server
728 mkdir project
729 cd project
b1889c36 730 git init
2b0d1033 731 git remote add origin server:/pub/project
762656e0 732 git config --add remote.origin.fetch '+refs/remotes/*:refs/remotes/*'
2b0d1033 733 git fetch
9e77353e
JK
734# Create a local branch from one of the branches just fetched
735 git checkout -b master FETCH_HEAD
647ac702 736# Initialize 'git svn' locally (be sure to use the same URL and -T/-b/-t options as were used on server)
2670ddce 737 git svn init http://svn.example.com/project
7d4aef40 738# Pull the latest changes from Subversion
b1889c36 739 git svn rebase
7d4aef40
AR
740------------------------------------------------------------------------
741
2eff1425
EW
742REBASE VS. PULL/MERGE
743---------------------
2e93115e 744
647ac702 745Originally, 'git svn' recommended that the 'remotes/git-svn' branch be
2eff1425 746pulled or merged from. This is because the author favored
483bc4f0
JN
747`git svn set-tree B` to commit a single head rather than the
748`git svn set-tree A..B` notation to commit multiple commits.
2eff1425 749
483bc4f0 750If you use `git svn set-tree A..B` to commit several diffs and you do
2eff1425 751not have the latest remotes/git-svn merged into my-branch, you should
483bc4f0 752use `git svn rebase` to update your work branch instead of `git pull` or
ccf497de 753`git merge`. `pull`/`merge` can cause non-linear history to be flattened
2eff1425
EW
754when committing into SVN, which can lead to merge commits reversing
755previous commits in SVN.
2e93115e 756
3397f9df
EW
757DESIGN PHILOSOPHY
758-----------------
759Merge tracking in Subversion is lacking and doing branched development
647ac702 760with Subversion can be cumbersome as a result. While 'git svn' can track
bd43098c
EW
761copy history (including branches and tags) for repositories adopting a
762standard layout, it cannot yet represent merge history that happened
763inside git back upstream to SVN users. Therefore it is advised that
764users keep history as linear as possible inside git to ease
765compatibility with SVN (see the CAVEATS section below).
1d52aba8 766
aabb2e51
EW
767CAVEATS
768-------
769
770For the sake of simplicity and interoperating with a less-capable system
647ac702
YD
771(SVN), it is recommended that all 'git svn' users clone, fetch and dcommit
772directly from the SVN server, and avoid all 'git clone'/'pull'/'merge'/'push'
aabb2e51
EW
773operations between git repositories and branches. The recommended
774method of exchanging code between git branches and users is
647ac702 775'git format-patch' and 'git am', or just 'dcommit'ing to the SVN repository.
aabb2e51 776
647ac702 777Running 'git merge' or 'git pull' is NOT recommended on a branch you
483bc4f0 778plan to 'dcommit' from. Subversion does not represent merges in any
aabb2e51
EW
779reasonable or useful fashion; so users using Subversion cannot see any
780merges you've made. Furthermore, if you merge or pull from a git branch
483bc4f0 781that is a mirror of an SVN branch, 'dcommit' may commit to the wrong
aabb2e51
EW
782branch.
783
ce45a45f
TR
784If you do merge, note the following rule: 'git svn dcommit' will
785attempt to commit on top of the SVN commit named in
786------------------------------------------------------------------------
787git log --grep=^git-svn-id: --first-parent -1
788------------------------------------------------------------------------
789You 'must' therefore ensure that the most recent commit of the branch
790you want to dcommit to is the 'first' parent of the merge. Chaos will
791ensue otherwise, especially if the first parent is an older commit on
792the same SVN branch.
793
647ac702
YD
794'git clone' does not clone branches under the refs/remotes/ hierarchy or
795any 'git svn' metadata, or config. So repositories created and managed with
796using 'git svn' should use 'rsync' for cloning, if cloning is to be done
aabb2e51
EW
797at all.
798
647ac702 799Since 'dcommit' uses rebase internally, any git branches you 'git push' to
483bc4f0 800before 'dcommit' on will require forcing an overwrite of the existing ref
aabb2e51 801on the remote repository. This is generally considered bad practice,
483bc4f0 802see the linkgit:git-push[1] documentation for details.
aabb2e51 803
483bc4f0 804Do not use the --amend option of linkgit:git-commit[1] on a change you've
aabb2e51
EW
805already dcommitted. It is considered bad practice to --amend commits
806you've already pushed to a remote repository for other users, and
807dcommit with SVN is analogous to that.
808
647ac702 809When using multiple --branches or --tags, 'git svn' does not automatically
ab81a364
MB
810handle name collisions (for example, if two branches from different paths have
811the same name, or if a branch and a tag have the same name). In these cases,
812use 'init' to set up your git repository then, before your first 'fetch', edit
813the .git/config file so that the branches and tags are associated with
814different name spaces. For example:
815
816 branches = stable/*:refs/remotes/svn/stable/*
817 branches = debug/*:refs/remotes/svn/debug/*
818
3397f9df
EW
819BUGS
820----
e8f5d908 821
a81ed0b6
EW
822We ignore all SVN properties except svn:executable. Any unhandled
823properties are logged to $GIT_DIR/svn/<refname>/unhandled.log
3397f9df 824
bbe0c9b8
EW
825Renamed and copied directories are not detected by git and hence not
826tracked when committing to SVN. I do not plan on adding support for
827this as it's quite difficult and time-consuming to get working for all
a81ed0b6
EW
828the possible corner cases (git doesn't do it, either). Committing
829renamed and copied files are fully supported if they're similar enough
830for git to detect them.
bbe0c9b8 831
a836a0e1
EW
832CONFIGURATION
833-------------
834
647ac702 835'git svn' stores [svn-remote] configuration information in the
a836a0e1
EW
836repository .git/config file. It is similar the core git
837[remote] sections except 'fetch' keys do not accept glob
838arguments; but they are instead handled by the 'branches'
839and 'tags' keys. Since some SVN repositories are oddly
840configured with multiple projects glob expansions such those
841listed below are allowed:
842
843------------------------------------------------------------------------
844[svn-remote "project-a"]
845 url = http://server.org/svn
0e5e69a3 846 fetch = trunk/project-a:refs/remotes/project-a/trunk
a836a0e1
EW
847 branches = branches/*/project-a:refs/remotes/project-a/branches/*
848 tags = tags/*/project-a:refs/remotes/project-a/tags/*
a836a0e1
EW
849------------------------------------------------------------------------
850
4ddef0e6 851Keep in mind that the '\*' (asterisk) wildcard of the local ref
d37a8de0 852(right of the ':') *must* be the farthest right path component;
bad542f0 853however the remote wildcard may be anywhere as long as it's an
02783075 854independent path component (surrounded by '/' or EOL). This
a836a0e1 855type of configuration is not automatically created by 'init' and
647ac702 856should be manually entered with a text-editor or using 'git config'.
a836a0e1 857
07576208
JS
858It is also possible to fetch a subset of branches or tags by using a
859comma-separated list of names within braces. For example:
860
861------------------------------------------------------------------------
862[svn-remote "huge-project"]
863 url = http://server.org/svn
864 fetch = trunk/src:refs/remotes/trunk
865 branches = branches/{red,green}/src:refs/remotes/branches/*
866 tags = tags/{1.0,2.0}/src:refs/remotes/tags/*
867------------------------------------------------------------------------
868
869Note that git-svn keeps track of the highest revision in which a branch
870or tag has appeared. If the subset of branches or tags is changed after
871fetching, then .git/svn/.metadata must be manually edited to remove (or
872reset) branches-maxRev and/or tags-maxRev as appropriate.
873
2e93115e
EW
874SEE ALSO
875--------
5162e697 876linkgit:git-rebase[1]
2e93115e 877
3397f9df
EW
878Author
879------
880Written by Eric Wong <normalperson@yhbt.net>.
881
882Documentation
883-------------
884Written by Eric Wong <normalperson@yhbt.net>.