da68f6d7385ecf1a4310c4742ea328ff55e6a4e4
1 git-svn(1)
2 ==========
4 NAME
5 ----
6 git-svn - Bidirectional operation between a single Subversion branch and git
8 SYNOPSIS
9 --------
10 'git-svn' <command> [options] [arguments]
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.
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.
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).
28 COMMANDS
29 --------
30 --
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.
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)
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.
61 --prefix=<prefix>
62 This allows one to specify a prefix which is prepended
63 to the names of remotes if trunk/branches/tags are
64 specified. The prefix does not automatically include a
65 trailing slash, so be sure you include one in the
66 argument if that is what you want. This is useful if
67 you wish to track multiple projects that share a common
68 repository.
70 'fetch'::
72 Fetch unfetched revisions from the Subversion remote we are
73 tracking. The name of the [svn-remote "..."] section in the
74 .git/config file may be specified as an optional command-line
75 argument.
77 'clone'::
78 Runs 'init' and 'fetch'. It will automatically create a
79 directory based on the basename of the URL passed to it;
80 or if a second argument is passed; it will create a directory
81 and work within that. It accepts all arguments that the
82 'init' and 'fetch' commands accept; with the exception of
83 '--fetch-all'. After a repository is cloned, the 'fetch'
84 command will be able to update revisions without affecting
85 the working tree; and the 'rebase' command will be able
86 to update the working tree with the latest changes.
88 'rebase'::
89 This fetches revisions from the SVN parent of the current HEAD
90 and rebases the current (uncommitted to SVN) work against it.
92 This works similarly to 'svn update' or 'git-pull' except that
93 it preserves linear history with 'git-rebase' instead of
94 'git-merge' for ease of dcommit-ing with git-svn.
96 This accepts all options that 'git-svn fetch' and 'git-rebase'
97 accepts. However '--fetch-all' only fetches from the current
98 [svn-remote], and not all [svn-remote] definitions.
100 Like 'git-rebase'; this requires that the working tree be clean
101 and have no uncommitted changes.
103 'dcommit'::
104 Commit each diff from a specified head directly to the SVN
105 repository, and then rebase or reset (depending on whether or
106 not there is a diff between SVN and head). This will create
107 a revision in SVN for each commit in git.
108 It is recommended that you run git-svn fetch and rebase (not
109 pull or merge) your commits against the latest changes in the
110 SVN repository.
111 An optional command-line argument may be specified as an
112 alternative to HEAD.
113 This is advantageous over 'set-tree' (below) because it produces
114 cleaner, more linear history.
116 'log'::
117 This should make it easy to look up svn log messages when svn
118 users refer to -r/--revision numbers.
120 The following features from `svn log' are supported:
122 --revision=<n>[:<n>] - is supported, non-numeric args are not:
123 HEAD, NEXT, BASE, PREV, etc ...
124 -v/--verbose - it's not completely compatible with
125 the --verbose output in svn log, but
126 reasonably close.
127 --limit=<n> - is NOT the same as --max-count,
128 doesn't count merged/excluded commits
129 --incremental - supported
131 New features:
133 --show-commit - shows the git commit sha1, as well
134 --oneline - our version of --pretty=oneline
136 Any other arguments are passed directly to `git log'
138 'set-tree'::
139 You should consider using 'dcommit' instead of this command.
140 Commit specified commit or tree objects to SVN. This relies on
141 your imported fetch data being up-to-date. This makes
142 absolutely no attempts to do patching when committing to SVN, it
143 simply overwrites files with those specified in the tree or
144 commit. All merging is assumed to have taken place
145 independently of git-svn functions.
147 'show-ignore'::
148 Recursively finds and lists the svn:ignore property on
149 directories. The output is suitable for appending to
150 the $GIT_DIR/info/exclude file.
152 'commit-diff'::
153 Commits the diff of two tree-ish arguments from the
154 command-line. This command is intended for interoperability with
155 git-svnimport and does not rely on being inside an git-svn
156 init-ed repository. This command takes three arguments, (a) the
157 original tree to diff against, (b) the new tree result, (c) the
158 URL of the target Subversion repository. The final argument
159 (URL) may be omitted if you are working from a git-svn-aware
160 repository (that has been init-ed with git-svn).
161 The -r<revision> option is required for this.
163 --
165 OPTIONS
166 -------
167 --
169 --shared[={false|true|umask|group|all|world|everybody}]::
170 --template=<template_directory>::
171 Only used with the 'init' command.
172 These are passed directly to gitlink:git-init[1].
174 -r <ARG>::
175 --revision <ARG>::
177 Used with the 'fetch' command.
179 This allows revision ranges for partial/cauterized history
180 to be supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges),
181 $NUMBER:HEAD, and BASE:$NUMBER are all supported.
183 This can allow you to make partial mirrors when running fetch;
184 but is generally not recommended because history will be skipped
185 and lost.
187 -::
188 --stdin::
190 Only used with the 'set-tree' command.
192 Read a list of commits from stdin and commit them in reverse
193 order. Only the leading sha1 is read from each line, so
194 git-rev-list --pretty=oneline output can be used.
196 --rmdir::
198 Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
200 Remove directories from the SVN tree if there are no files left
201 behind. SVN can version empty directories, and they are not
202 removed by default if there are no files left in them. git
203 cannot version empty directories. Enabling this flag will make
204 the commit to SVN act like git.
206 config key: svn.rmdir
208 -e::
209 --edit::
211 Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
213 Edit the commit message before committing to SVN. This is off by
214 default for objects that are commits, and forced on when committing
215 tree objects.
217 config key: svn.edit
219 -l<num>::
220 --find-copies-harder::
222 Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
224 They are both passed directly to git-diff-tree see
225 gitlink:git-diff-tree[1] for more information.
227 [verse]
228 config key: svn.l
229 config key: svn.findcopiesharder
231 -A<filename>::
232 --authors-file=<filename>::
234 Syntax is compatible with the files used by git-svnimport and
235 git-cvsimport:
237 ------------------------------------------------------------------------
238 loginname = Joe User <user@example.com>
239 ------------------------------------------------------------------------
241 If this option is specified and git-svn encounters an SVN
242 committer name that does not exist in the authors-file, git-svn
243 will abort operation. The user will then have to add the
244 appropriate entry. Re-running the previous git-svn command
245 after the authors-file is modified should continue operation.
247 config key: svn.authorsfile
249 -q::
250 --quiet::
251 Make git-svn less verbose.
253 --repack[=<n>]::
254 --repack-flags=<flags>
255 These should help keep disk usage sane for large fetches
256 with many revisions.
258 --repack takes an optional argument for the number of revisions
259 to fetch before repacking. This defaults to repacking every
260 1000 commits fetched if no argument is specified.
262 --repack-flags are passed directly to gitlink:git-repack[1].
264 config key: svn.repack
265 config key: svn.repackflags
267 -m::
268 --merge::
269 -s<strategy>::
270 --strategy=<strategy>::
272 These are only used with the 'dcommit' and 'rebase' commands.
274 Passed directly to git-rebase when using 'dcommit' if a
275 'git-reset' cannot be used (see dcommit).
277 -n::
278 --dry-run::
280 This is only used with the 'dcommit' command.
282 Print out the series of git arguments that would show
283 which diffs would be committed to SVN.
285 --
287 ADVANCED OPTIONS
288 ----------------
289 --
291 -i<GIT_SVN_ID>::
292 --id <GIT_SVN_ID>::
294 This sets GIT_SVN_ID (instead of using the environment). This
295 allows the user to override the default refname to fetch from
296 when tracking a single URL. The 'log' and 'dcommit' commands
297 no longer require this switch as an argument.
299 -R<remote name>::
300 --svn-remote <remote name>::
301 Specify the [svn-remote "<remote name>"] section to use,
302 this allows SVN multiple repositories to be tracked.
303 Default: "svn"
305 --follow-parent::
306 This is especially helpful when we're tracking a directory
307 that has been moved around within the repository, or if we
308 started tracking a branch and never tracked the trunk it was
309 descended from. This feature is enabled by default, use
310 --no-follow-parent to disable it.
312 config key: svn.followparent
314 --
315 CONFIG FILE-ONLY OPTIONS
316 ------------------------
317 --
319 svn.noMetadata::
320 svn-remote.<name>.noMetadata::
321 This gets rid of the git-svn-id: lines at the end of every commit.
323 If you lose your .git/svn/git-svn/.rev_db file, git-svn will not
324 be able to rebuild it and you won't be able to fetch again,
325 either. This is fine for one-shot imports.
327 The 'git-svn log' command will not work on repositories using
328 this, either. Using this conflicts with the 'useSvmProps'
329 option for (hopefully) obvious reasons.
331 svn.useSvmProps::
332 svn-remote.<name>.useSvmProps::
333 This allows git-svn to re-map repository URLs and UUIDs from
334 mirrors created using SVN::Mirror (or svk) for metadata.
336 If an SVN revision has a property, "svm:headrev", it is likely
337 that the revision was created by SVN::Mirror (also used by SVK).
338 The property contains a repository UUID and a revision. We want
339 to make it look like we are mirroring the original URL, so
340 introduce a helper function that returns the original identity
341 URL and UUID, and use it when generating metadata in commit
342 messages.
344 svn.useSvnsyncProps::
345 svn-remote.<name>.useSvnsyncprops::
346 Similar to the useSvmProps option; this is for users
347 of the svnsync(1) command distributed with SVN 1.4.x and
348 later.
350 svn-remote.<name>.rewriteRoot::
351 This allows users to create repositories from alternate
352 URLs. For example, an administrator could run git-svn on the
353 server locally (accessing via file://) but wish to distribute
354 the repository with a public http:// or svn:// URL in the
355 metadata so users of it will see the public URL.
357 Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps
358 options all affect the metadata generated and used by git-svn; they
359 *must* be set in the configuration file before any history is imported
360 and these settings should never be changed once they are set.
362 Additionally, only one of these four options can be used per-svn-remote
363 section because they affect the 'git-svn-id:' metadata line.
365 --
367 Basic Examples
368 ~~~~~~~~~~~~~~
370 Tracking and contributing to a the trunk of a Subversion-managed project:
372 ------------------------------------------------------------------------
373 # Clone a repo (like git clone):
374 git-svn clone http://svn.foo.org/project/trunk
375 # Enter the newly cloned directory:
376 cd trunk
377 # You should be on master branch, double-check with git-branch
378 git branch
379 # Do some work and commit locally to git:
380 git commit ...
381 # Something is committed to SVN, rebase your local changes against the
382 # latest changes in SVN:
383 git-svn rebase
384 # Now commit your changes (that were committed previously using git) to SVN,
385 # as well as automatically updating your working HEAD:
386 git-svn dcommit
387 # Append svn:ignore settings to the default git exclude file:
388 git-svn show-ignore >> .git/info/exclude
389 ------------------------------------------------------------------------
391 Tracking and contributing to an entire Subversion-managed project
392 (complete with a trunk, tags and branches):
394 ------------------------------------------------------------------------
395 # Clone a repo (like git clone):
396 git-svn clone http://svn.foo.org/project -T trunk -b branches -t tags
397 # View all branches and tags you have cloned:
398 git branch -r
399 # Reset your master to trunk (or any other branch, replacing 'trunk'
400 # with the appropriate name):
401 git reset --hard remotes/trunk
402 # You may only dcommit to one branch/tag/trunk at a time. The usage
403 # of dcommit/rebase/show-ignore should be teh same as above.
404 ------------------------------------------------------------------------
406 REBASE VS. PULL/MERGE
407 ---------------------
409 Originally, git-svn recommended that the remotes/git-svn branch be
410 pulled or merged from. This is because the author favored
411 'git-svn set-tree B' to commit a single head rather than the
412 'git-svn set-tree A..B' notation to commit multiple commits.
414 If you use 'git-svn set-tree A..B' to commit several diffs and you do
415 not have the latest remotes/git-svn merged into my-branch, you should
416 use 'git-svn rebase' to update your work branch instead of 'git pull' or
417 'git merge'. 'pull/merge' can cause non-linear history to be flattened
418 when committing into SVN, which can lead to merge commits reversing
419 previous commits in SVN.
421 DESIGN PHILOSOPHY
422 -----------------
423 Merge tracking in Subversion is lacking and doing branched development
424 with Subversion is cumbersome as a result. git-svn does not do
425 automated merge/branch tracking by default and leaves it entirely up to
426 the user on the git side. git-svn does however follow copy
427 history of the directory that it is tracking, however (much like
428 how 'svn log' works).
430 BUGS
431 ----
433 We ignore all SVN properties except svn:executable. Any unhandled
434 properties are logged to $GIT_DIR/svn/<refname>/unhandled.log
436 Renamed and copied directories are not detected by git and hence not
437 tracked when committing to SVN. I do not plan on adding support for
438 this as it's quite difficult and time-consuming to get working for all
439 the possible corner cases (git doesn't do it, either). Committing
440 renamed and copied files are fully supported if they're similar enough
441 for git to detect them.
443 CONFIGURATION
444 -------------
446 git-svn stores [svn-remote] configuration information in the
447 repository .git/config file. It is similar the core git
448 [remote] sections except 'fetch' keys do not accept glob
449 arguments; but they are instead handled by the 'branches'
450 and 'tags' keys. Since some SVN repositories are oddly
451 configured with multiple projects glob expansions such those
452 listed below are allowed:
454 ------------------------------------------------------------------------
455 [svn-remote "project-a"]
456 url = http://server.org/svn
457 branches = branches/*/project-a:refs/remotes/project-a/branches/*
458 tags = tags/*/project-a:refs/remotes/project-a/tags/*
459 trunk = trunk/project-a:refs/remotes/project-a/trunk
460 ------------------------------------------------------------------------
462 Keep in mind that the '*' (asterisk) wildcard of the local ref
463 (left of the ':') *must* be the farthest right path component;
464 however the remote wildcard may be anywhere as long as it's own
465 independent path componet (surrounded by '/' or EOL). This
466 type of configuration is not automatically created by 'init' and
467 should be manually entered with a text-editor or using
468 gitlink:git-config[1]
470 SEE ALSO
471 --------
472 gitlink:git-rebase[1]
474 Author
475 ------
476 Written by Eric Wong <normalperson@yhbt.net>.
478 Documentation
479 -------------
480 Written by Eric Wong <normalperson@yhbt.net>.