1GIT-SVN(1) Git Manual GIT-SVN(1)
2
6 git-svn - Bidirectional operation between a single Subversion branch
7 and git
8
10 git-svn <command> [options] [arguments]
11
13 git-svn is a simple conduit for changesets between Subversion and git.
14 It is not to be confused with git-svnimport(1), which is read-only.
15 git-svn was originally designed for an individual developer who wants a
17 bidirectional flow of changesets between a single branch in Subversion
18 and an arbitrary number of branches in git. Since its inception,
19 git-svn has gained the ability to track multiple branches in a manner
20 similar to git-svnimport.
21 git-svn is especially useful when it comes to tracking repositories not
23 organized in the way Subversion developers recommend (trunk, branches,
24 tags directories).
25
27 init
28 Initializes an empty git repository with additional metadata
29 directories for git-svn. The Subversion URL may be specified as a
30 command-line argument, or as full URL arguments to -T/-t/-b.
31 Optionally, the target directory to operate on can be specified as
32 a second argument. Normally this command initializes the current
33 directory.
34 -T<trunk_subdir>, --trunk=<trunk_subdir>, -t<tags_subdir>,
36 --tags=<tags_subdir>, -b<branches_subdir>,
37 --branches=<branches_subdir>, -s, --stdlayout
38 These are optional command-line options for init. Each of these
39 flags can point to a relative repository path
40 (--tags=project/tags´) or a full url
41 (--tags=https://foo.org/project/tags). The option --stdlayout
42 is a shorthand way of setting trunk,tags,branches as the
43 relative paths, which is the Subversion default. If any of the
44 other options are given as well, they take precedence.
45 --no-metadata
47 Set the noMetadata option in the [svn-remote] config.
48 --use-svm-props
50 Set the useSvmProps option in the [svn-remote] config.
51 --use-svnsync-props
53 Set the useSvnsyncProps option in the [svn-remote] config.
54 --rewrite-root=<URL>
56 Set the rewriteRoot option in the [svn-remote] config.
57 --username=<USER>
59 For transports that SVN handles authentication for (http,
60 https, and plain svn), specify the username. For other
61 transports (eg svn+ssh://), you must include the username in
62 the URL, eg svn+ssh://foo@svn.bar.com/project
63 --prefix=<prefix>
65 This allows one to specify a prefix which is prepended to the
66 names of remotes if trunk/branches/tags are specified. The
67 prefix does not automatically include a trailing slash, so be
68 sure you include one in the argument if that is what you want.
69 If --branches/-b is specified, the prefix must include a
70 trailing slash. Setting a prefix is useful if you wish to track
71 multiple projects that share a common repository.
72 fetch
74 Fetch unfetched revisions from the Subversion remote we are
75 tracking. The name of the [svn-remote "..."] section in the
76 .git/config file may be specified as an optional command-line
77 argument.
78 clone
80 Runs init and fetch. It will automatically create a directory based
81 on the basename of the URL passed to it; or if a second argument is
82 passed; it will create a directory and work within that. It accepts
83 all arguments that the init and fetch commands accept; with the
84 exception of --fetch-all. After a repository is cloned, the fetch
85 command will be able to update revisions without affecting the
86 working tree; and the rebase command will be able to update the
87 working tree with the latest changes.
88 rebase
90 This fetches revisions from the SVN parent of the current HEAD and
91 rebases the current (uncommitted to SVN) work against it.
92 This works similarly to svn update or git-pull except that it
94 preserves linear history with git-rebase instead of git-merge for
95 ease of dcommiting with git-svn.
96 This accepts all options that git-svn fetch and git-rebase accepts.
98 However --fetch-all only fetches from the current [svn-remote], and
99 not all [svn-remote] definitions.
100 Like git-rebase; this requires that the working tree be clean and
102 have no uncommitted changes.
103 -l, --local
105 Do not fetch remotely; only run git-rebase against the last
106 fetched commit from the upstream SVN.
107 dcommit
109 Commit each diff from a specified head directly to the SVN
110 repository, and then rebase or reset (depending on whether or not
111 there is a diff between SVN and head). This will create a revision
112 in SVN for each commit in git. It is recommended that you run
113 git-svn fetch and rebase (not pull or merge) your commits against
114 the latest changes in the SVN repository. An optional command-line
115 argument may be specified as an alternative to HEAD. This is
116 advantageous over set-tree (below) because it produces cleaner,
117 more linear history.
118 --no-rebase
120 After committing, do not rebase or reset.
121 log
123 This should make it easy to look up svn log messages when svn users
124 refer to -r/--revision numbers.
125 The following features from `svn log´ are supported:
127 --revision=<n>[:<n>]
129 is supported, non-numeric args are not: HEAD, NEXT, BASE, PREV,
130 etc ...
131 -v/--verbose
133 it´s not completely compatible with the --verbose output in svn
134 log, but reasonably close.
135 --limit=<n>
137 is NOT the same as --max-count, doesn´t count merged/excluded
138 commits
139 --incremental
141 supported
142 New features:
144 --show-commit
146 shows the git commit sha1, as well
147 --oneline
149 our version of --pretty=oneline
150 Any other arguments are passed directly to `git log´
152 find-rev
154 When given an SVN revision number of the form rN, returns the
155 corresponding git commit hash (this can optionally be followed by a
156 tree-ish to specify which branch should be searched). When given a
157 tree-ish, returns the corresponding SVN revision number.
158 set-tree
160 You should consider using dcommit instead of this command. Commit
161 specified commit or tree objects to SVN. This relies on your
162 imported fetch data being up-to-date. This makes absolutely no
163 attempts to do patching when committing to SVN, it simply
164 overwrites files with those specified in the tree or commit. All
165 merging is assumed to have taken place independently of git-svn
166 functions.
167 show-ignore
169 Recursively finds and lists the svn:ignore property on directories.
170 The output is suitable for appending to the $GIT_DIR/info/exclude
171 file.
172 commit-diff
174 Commits the diff of two tree-ish arguments from the command-line.
175 This command is intended for interoperability with git-svnimport
176 and does not rely on being inside an git-svn init-ed repository.
177 This command takes three arguments, (a) the original tree to diff
178 against, (b) the new tree result, (c) the URL of the target
179 Subversion repository. The final argument (URL) may be omitted if
180 you are working from a git-svn-aware repository (that has been
181 init-ed with git-svn). The -r<revision> option is required for
182 this.
183
185 --shared[={false|true|umask|group|all|world|everybody}],
186 --template=<template_directory>
187 Only used with the init command. These are passed directly to git-
188 init(1).
189 -r <ARG>, --revision <ARG>
191 Used with the fetch command.
192 This allows revision ranges for partial/cauterized history to be
194 supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges),
195 $NUMBER:HEAD, and BASE:$NUMBER are all supported.
196 This can allow you to make partial mirrors when running fetch; but
198 is generally not recommended because history will be skipped and
199 lost.
200 -, --stdin
202 Only used with the set-tree command.
203 Read a list of commits from stdin and commit them in reverse order.
205 Only the leading sha1 is read from each line, so git-rev-list
206 --pretty=oneline output can be used.
207 --rmdir
209 Only used with the dcommit, set-tree and commit-diff commands.
210 Remove directories from the SVN tree if there are no files left
212 behind. SVN can version empty directories, and they are not removed
213 by default if there are no files left in them. git cannot version
214 empty directories. Enabling this flag will make the commit to SVN
215 act like git.
216 config key: svn.rmdir
218 -e, --edit
220 Only used with the dcommit, set-tree and commit-diff commands.
221 Edit the commit message before committing to SVN. This is off by
223 default for objects that are commits, and forced on when committing
224 tree objects.
225 config key: svn.edit
227 -l<num>, --find-copies-harder
229 Only used with the dcommit, set-tree and commit-diff commands.
230 They are both passed directly to git-diff-tree see git-diff-tree(1)
232 for more information.
233 config key: svn.l
236 config key: svn.findcopiesharder
237 -A<filename>, --authors-file=<filename>
239 Syntax is compatible with the files used by git-svnimport and
240 git-cvsimport:
241 loginname = Joe User <user@example.com>
245 If this option is specified and git-svn encounters an SVN committer
247 name that does not exist in the authors-file, git-svn will abort
248 operation. The user will then have to add the appropriate entry.
249 Re-running the previous git-svn command after the authors-file is
250 modified should continue operation.
251 config key: svn.authorsfile
253 -q, --quiet
255 Make git-svn less verbose.
256 --repack[=<n>], --repack-flags=<flags>
258 These should help keep disk usage sane for large fetches with many
259 revisions.
260 --repack takes an optional argument for the number of revisions to
262 fetch before repacking. This defaults to repacking every 1000
263 commits fetched if no argument is specified.
264 --repack-flags are passed directly to git-repack(1).
266 config key: svn.repack
269 config key: svn.repackflags
270 -m, --merge, -s<strategy>, --strategy=<strategy>
272 These are only used with the dcommit and rebase commands.
273 Passed directly to git-rebase when using dcommit if a git-reset
275 cannot be used (see dcommit).
276 -n, --dry-run
278 This is only used with the dcommit command.
279 Print out the series of git arguments that would show which diffs
281 would be committed to SVN.
282
284 -i<GIT_SVN_ID>, --id <GIT_SVN_ID>
285 This sets GIT_SVN_ID (instead of using the environment). This
286 allows the user to override the default refname to fetch from when
287 tracking a single URL. The log and dcommit commands no longer
288 require this switch as an argument.
289 -R<remote name>, --svn-remote <remote name>
291 Specify the [svn-remote "<remote name>"] section to use, this
292 allows SVN multiple repositories to be tracked. Default: "svn"
293 --follow-parent
295 This is especially helpful when we´re tracking a directory that has
296 been moved around within the repository, or if we started tracking
297 a branch and never tracked the trunk it was descended from. This
298 feature is enabled by default, use --no-follow-parent to disable
299 it.
300 config key: svn.followparent
302
304 svn.noMetadata, svn-remote.<name>.noMetadata
305 This gets rid of the git-svn-id: lines at the end of every commit.
306 If you lose your .git/svn/git-svn/.rev_db file, git-svn will not be
308 able to rebuild it and you won´t be able to fetch again, either.
309 This is fine for one-shot imports.
310 The git-svn log command will not work on repositories using this,
312 either. Using this conflicts with the useSvmProps option for
313 (hopefully) obvious reasons.
314 svn.useSvmProps, svn-remote.<name>.useSvmProps
316 This allows git-svn to re-map repository URLs and UUIDs from
317 mirrors created using SVN::Mirror (or svk) for metadata.
318 If an SVN revision has a property, "svm:headrev", it is likely that
320 the revision was created by SVN::Mirror (also used by SVK). The
321 property contains a repository UUID and a revision. We want to make
322 it look like we are mirroring the original URL, so introduce a
323 helper function that returns the original identity URL and UUID,
324 and use it when generating metadata in commit messages.
325 svn.useSvnsyncProps, svn-remote.<name>.useSvnsyncprops
327 Similar to the useSvmProps option; this is for users of the
328 svnsync(1) command distributed with SVN 1.4.x and later.
329 svn-remote.<name>.rewriteRoot
331 This allows users to create repositories from alternate URLs. For
332 example, an administrator could run git-svn on the server locally
333 (accessing via file://) but wish to distribute the repository with
334 a public http:// or svn:// URL in the metadata so users of it will
335 see the public URL.
336 Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps
338 options all affect the metadata generated and used by git-svn; they
339 must be set in the configuration file before any history is
340 imported and these settings should never be changed once they are
341 set.
342 Additionally, only one of these four options can be used
344 per-svn-remote section because they affect the git-svn-id: metadata
345 line.
346
348 Tracking and contributing to a the trunk of a Subversion-managed
349 project:
350 # Clone a repo (like git clone):
354 git-svn clone http://svn.foo.org/project/trunk
355 # Enter the newly cloned directory:
356 cd trunk
357 # You should be on master branch, double-check with git-branch
358 git branch
359 # Do some work and commit locally to git:
360 git commit ...
361 # Something is committed to SVN, rebase your local changes against the
362 # latest changes in SVN:
363 git-svn rebase
364 # Now commit your changes (that were committed previously using git) to SVN,
365 # as well as automatically updating your working HEAD:
366 git-svn dcommit
367 # Append svn:ignore settings to the default git exclude file:
368 git-svn show-ignore >> .git/info/exclude
369 Tracking and contributing to an entire Subversion-managed project
371 (complete with a trunk, tags and branches):
372 # Clone a repo (like git clone):
376 git-svn clone http://svn.foo.org/project -T trunk -b branches -t tags
377 # View all branches and tags you have cloned:
378 git branch -r
379 # Reset your master to trunk (or any other branch, replacing ´trunk´
380 # with the appropriate name):
381 git reset --hard remotes/trunk
382 # You may only dcommit to one branch/tag/trunk at a time. The usage
383 # of dcommit/rebase/show-ignore should be the same as above.
384 The initial git-svn clone can be quite time-consuming (especially for
386 large Subversion repositories). If multiple people (or one person with
387 multiple machines) want to use git-svn to interact with the same
388 Subversion repository, you can do the initial git-svn clone to a
389 repository on a server and have each person clone that repository with
390 git clone:
391 # Do the initial import on a server
395 ssh server "cd /pub && git-svn clone http://svn.foo.org/project
396 # Clone locally
397 git clone server:/pub/project
398 # Tell git-svn which branch contains the Subversion commits
399 git update-ref refs/remotes/git-svn origin/master
400 # Initialize git-svn locally (be sure to use the same URL and -T/-b/-t options as were used on server)
401 git-svn init http://svn.foo.org/project
402 # Pull the latest changes from Subversion
403 git-svn rebase
404
407 Originally, git-svn recommended that the remotes/git-svn branch be
408 pulled or merged from. This is because the author favored git-svn
409 set-tree B to commit a single head rather than the git-svn set-tree
410 A..B notation to commit multiple commits.
411 If you use git-svn set-tree A..B to commit several diffs and you do not
413 have the latest remotes/git-svn merged into my-branch, you should use
414 git-svn rebase to update your work branch instead of git pull or git
415 merge. pull/merge can cause non-linear history to be flattened when
416 committing into SVN, which can lead to merge commits reversing previous
417 commits in SVN.
418
420 Merge tracking in Subversion is lacking and doing branched development
421 with Subversion can be cumbersome as a result. While git-svn can track
422 copy history (including branches and tags) for repositories adopting a
423 standard layout, it cannot yet represent merge history that happened
424 inside git back upstream to SVN users. Therefore it is advised that
425 users keep history as linear as possible inside git to ease
426 compatibility with SVN (see the CAVEATS section below).
427
429 For the sake of simplicity and interoperating with a less-capable
430 system (SVN), it is recommended that all git-svn users clone, fetch and
431 dcommit directly from the SVN server, and avoid all
432 git-clone/pull/merge/push operations between git repositories and
433 branches. The recommended method of exchanging code between git
434 branches and users is git-format-patch and git-am, or just dcommiting
435 to the SVN repository.
436 Running git-merge or git-pull is NOT recommended on a branch you plan
438 to dcommit from. Subversion does not represent merges in any reasonable
439 or useful fashion; so users using Subversion cannot see any merges
440 you´ve made. Furthermore, if you merge or pull from a git branch that
441 is a mirror of an SVN branch, dcommit may commit to the wrong branch.
442 git-clone does not clone branches under the refs/remotes/ hierarchy or
444 any git-svn metadata, or config. So repositories created and managed
445 with using git-svn should use rsync(1) for cloning, if cloning is to be
446 done at all.
447 Since dcommit uses rebase internally, any git branches you git-push to
449 before dcommit on will require forcing an overwrite of the existing ref
450 on the remote repository. This is generally considered bad practice,
451 see the git-push(1) documentation for details.
452 Do not use the --amend option of git-commit(1) on a change you´ve
454 already dcommitted. It is considered bad practice to --amend commits
455 you´ve already pushed to a remote repository for other users, and
456 dcommit with SVN is analogous to that.
457
459 We ignore all SVN properties except svn:executable. Any unhandled
460 properties are logged to $GIT_DIR/svn/<refname>/unhandled.log
461 Renamed and copied directories are not detected by git and hence not
463 tracked when committing to SVN. I do not plan on adding support for
464 this as it´s quite difficult and time-consuming to get working for all
465 the possible corner cases (git doesn´t do it, either). Committing
466 renamed and copied files are fully supported if they´re similar enough
467 for git to detect them.
468
470 git-svn stores [svn-remote] configuration information in the repository
471 .git/config file. It is similar the core git [remote] sections except
472 fetch keys do not accept glob arguments; but they are instead handled
473 by the branches and tags keys. Since some SVN repositories are oddly
474 configured with multiple projects glob expansions such those listed
475 below are allowed:
476 [svn-remote "project-a"]
480 url = http://server.org/svn
481 branches = branches/*/project-a:refs/remotes/project-a/branches/*
482 tags = tags/*/project-a:refs/remotes/project-a/tags/*
483 trunk = trunk/project-a:refs/remotes/project-a/trunk
484 Keep in mind that the (asterisk) wildcard of the local ref (right of
486 the :) *must be the farthest right path component; however the remote
487 wildcard may be anywhere as long as it´s own independent path component
488 (surrounded by / or EOL). This type of configuration is not
489 automatically created by init and should be manually entered with a
490 text-editor or using git-config(1)
491
493 git-rebase(1)
494
496 Written by Eric Wong <normalperson@yhbt.net>.
497
499 Written by Eric Wong <normalperson@yhbt.net>.
500Git 1.5.3.3 10/09/2007 GIT-SVN(1)