Merge branch 'master' of ssh://Culex@repo.or.cz/srv/git/gitman-de
[gitman-de.git] / git-svn.txt
blobe7c0f1c959d39739e177096875dd8aac5fd185d9
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 --------
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 accept.  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.
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:
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
163 New features:
166 --show-commit;;
167         shows the git commit sha1, as well
168 --oneline;;
169         our version of --pretty=oneline
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.
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.
251 OPTIONS
252 -------
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 'git-init'.
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.
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 'git-repack'.
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.
379 ADVANCED OPTIONS
380 ----------------
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
407 CONFIG FILE-ONLY OPTIONS
408 ------------------------
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.
453 Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps
454 options all affect the metadata generated and used by 'git-svn'; they
455 *must* be set in the configuration file before any history is imported
456 and these settings should never be changed once they are set.
458 Additionally, only one of these four options can be used per-svn-remote
459 section because they affect the 'git-svn-id:' metadata line.
462 BASIC EXAMPLES
463 --------------
465 Tracking and contributing to the trunk of a Subversion-managed project:
467 ------------------------------------------------------------------------
468 # Clone a repo (like git clone):
469         git svn clone http://svn.foo.org/project/trunk
470 # Enter the newly cloned directory:
471         cd trunk
472 # You should be on master branch, double-check with git-branch
473         git branch
474 # Do some work and commit locally to git:
475         git commit ...
476 # Something is committed to SVN, rebase your local changes against the
477 # latest changes in SVN:
478         git svn rebase
479 # Now commit your changes (that were committed previously using git) to SVN,
480 # as well as automatically updating your working HEAD:
481         git svn dcommit
482 # Append svn:ignore settings to the default git exclude file:
483         git svn show-ignore >> .git/info/exclude
484 ------------------------------------------------------------------------
486 Tracking and contributing to an entire Subversion-managed project
487 (complete with a trunk, tags and branches):
489 ------------------------------------------------------------------------
490 # Clone a repo (like git clone):
491         git svn clone http://svn.foo.org/project -T trunk -b branches -t tags
492 # View all branches and tags you have cloned:
493         git branch -r
494 # Reset your master to trunk (or any other branch, replacing 'trunk'
495 # with the appropriate name):
496         git reset --hard remotes/trunk
497 # You may only dcommit to one branch/tag/trunk at a time.  The usage
498 # of dcommit/rebase/show-ignore should be the same as above.
499 ------------------------------------------------------------------------
501 The initial 'git-svn clone' can be quite time-consuming
502 (especially for large Subversion repositories). If multiple
503 people (or one person with multiple machines) want to use
504 'git-svn' to interact with the same Subversion repository, you can
505 do the initial 'git-svn clone' to a repository on a server and
506 have each person clone that repository with 'git-clone':
508 ------------------------------------------------------------------------
509 # Do the initial import on a server
510         ssh server "cd /pub && git svn clone http://svn.foo.org/project
511 # Clone locally - make sure the refs/remotes/ space matches the server
512         mkdir project
513         cd project
514         git init
515         git remote add origin server:/pub/project
516         git config --add remote.origin.fetch '+refs/remotes/*:refs/remotes/*'
517         git fetch
518 # Initialize git-svn locally (be sure to use the same URL and -T/-b/-t options as were used on server)
519         git svn init http://svn.foo.org/project
520 # Pull the latest changes from Subversion
521         git svn rebase
522 ------------------------------------------------------------------------
524 REBASE VS. PULL/MERGE
525 ---------------------
527 Originally, 'git-svn' recommended that the 'remotes/git-svn' branch be
528 pulled or merged from.  This is because the author favored
529 `git svn set-tree B` to commit a single head rather than the
530 `git svn set-tree A..B` notation to commit multiple commits.
532 If you use `git svn set-tree A..B` to commit several diffs and you do
533 not have the latest remotes/git-svn merged into my-branch, you should
534 use `git svn rebase` to update your work branch instead of `git pull` or
535 `git merge`.  `pull`/`merge' can cause non-linear history to be flattened
536 when committing into SVN, which can lead to merge commits reversing
537 previous commits in SVN.
539 DESIGN PHILOSOPHY
540 -----------------
541 Merge tracking in Subversion is lacking and doing branched development
542 with Subversion can be cumbersome as a result.  While 'git-svn' can track
543 copy history (including branches and tags) for repositories adopting a
544 standard layout, it cannot yet represent merge history that happened
545 inside git back upstream to SVN users.  Therefore it is advised that
546 users keep history as linear as possible inside git to ease
547 compatibility with SVN (see the CAVEATS section below).
549 CAVEATS
550 -------
552 For the sake of simplicity and interoperating with a less-capable system
553 (SVN), it is recommended that all 'git-svn' users clone, fetch and dcommit
554 directly from the SVN server, and avoid all 'git-clone'/'pull'/'merge'/'push'
555 operations between git repositories and branches.  The recommended
556 method of exchanging code between git branches and users is
557 'git-format-patch' and 'git-am', or just 'dcommit'ing to the SVN repository.
559 Running 'git-merge' or 'git-pull' is NOT recommended on a branch you
560 plan to 'dcommit' from.  Subversion does not represent merges in any
561 reasonable or useful fashion; so users using Subversion cannot see any
562 merges you've made.  Furthermore, if you merge or pull from a git branch
563 that is a mirror of an SVN branch, 'dcommit' may commit to the wrong
564 branch.
566 'git-clone' does not clone branches under the refs/remotes/ hierarchy or
567 any 'git-svn' metadata, or config.  So repositories created and managed with
568 using 'git-svn' should use 'rsync' for cloning, if cloning is to be done
569 at all.
571 Since 'dcommit' uses rebase internally, any git branches you 'git-push' to
572 before 'dcommit' on will require forcing an overwrite of the existing ref
573 on the remote repository.  This is generally considered bad practice,
574 see the linkgit:git-push[1] documentation for details.
576 Do not use the --amend option of linkgit:git-commit[1] on a change you've
577 already dcommitted.  It is considered bad practice to --amend commits
578 you've already pushed to a remote repository for other users, and
579 dcommit with SVN is analogous to that.
581 BUGS
582 ----
584 We ignore all SVN properties except svn:executable.  Any unhandled
585 properties are logged to $GIT_DIR/svn/<refname>/unhandled.log
587 Renamed and copied directories are not detected by git and hence not
588 tracked when committing to SVN.  I do not plan on adding support for
589 this as it's quite difficult and time-consuming to get working for all
590 the possible corner cases (git doesn't do it, either).  Committing
591 renamed and copied files are fully supported if they're similar enough
592 for git to detect them.
594 CONFIGURATION
595 -------------
597 'git-svn' stores [svn-remote] configuration information in the
598 repository .git/config file.  It is similar the core git
599 [remote] sections except 'fetch' keys do not accept glob
600 arguments; but they are instead handled by the 'branches'
601 and 'tags' keys.  Since some SVN repositories are oddly
602 configured with multiple projects glob expansions such those
603 listed below are allowed:
605 ------------------------------------------------------------------------
606 [svn-remote "project-a"]
607         url = http://server.org/svn
608         branches = branches/*/project-a:refs/remotes/project-a/branches/*
609         tags = tags/*/project-a:refs/remotes/project-a/tags/*
610         trunk = trunk/project-a:refs/remotes/project-a/trunk
611 ------------------------------------------------------------------------
613 Keep in mind that the '*' (asterisk) wildcard of the local ref
614 (right of the ':') *must* be the farthest right path component;
615 however the remote wildcard may be anywhere as long as it's own
616 independent path component (surrounded by '/' or EOL).   This
617 type of configuration is not automatically created by 'init' and
618 should be manually entered with a text-editor or using 'git-config'.
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>.