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