Code

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