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