Documentation: a few spelling fixes
[git/git.git] / Documentation / git-svn.txt
CommitLineData
3397f9df
EW
1git-svn(1)
2==========
3
4NAME
5----
0d313b2b 6git-svn - bidirectional operation between Subversion 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
16read-only and geared towards tracking multiple branches.
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
22similar to git-svnimport; but it cannot (yet) automatically detect new
23branches and tags like git-svnimport does.
3397f9df 24
0d313b2b
EW
25git-svn is especially useful when it comes to tracking repositories
26not organized in the way Subversion developers recommend (trunk,
27branches, tags directories).
3397f9df
EW
28
29COMMANDS
30--------
0ea4d4c9
JF
31--
32
33'init'::
3397f9df 34 Creates an empty git repository with additional metadata
81c5a0e6 35 directories for git-svn. The Subversion URL must be specified
e8f5d908
EW
36 as a command-line argument. Optionally, the target directory
37 to operate on can be specified as a second argument. Normally
38 this command initializes the current directory.
3397f9df 39
0ea4d4c9 40'fetch'::
3397f9df 41
0ea4d4c9
JF
42Fetch unfetched revisions from the Subversion URL we are
43tracking. refs/remotes/git-svn will be updated to the
44latest revision.
81c5a0e6 45
0ea4d4c9
JF
46Note: You should never attempt to modify the remotes/git-svn
47branch outside of git-svn. Instead, create a branch from
4511c899 48remotes/git-svn and work on that branch. Use the 'dcommit'
0ea4d4c9
JF
49command (see below) to write git commits back to
50remotes/git-svn.
b705ba43 51
0ea4d4c9
JF
52See '<<fetch-args,Additional Fetch Arguments>>' if you are interested in
53manually joining branches on commit.
54
b22d4497 55'dcommit'::
2eff1425 56 Commit each diff from a specified head directly to the SVN
b22d4497 57 repository, and then rebase or reset (depending on whether or
2eff1425
EW
58 not there is a diff between SVN and head). This will create
59 a revision in SVN for each commit in git.
60 It is recommended that you run git-svn fetch and rebase (not
61 pull or merge) your commits against the latest changes in the
62 SVN repository.
dd31da2f
EW
63 An optional command-line argument may be specified as an
64 alternative to HEAD.
3289e86e 65 This is advantageous over 'set-tree' (below) because it produces
b22d4497
EW
66 cleaner, more linear history.
67
e8f5d908
EW
68'log'::
69 This should make it easy to look up svn log messages when svn
70 users refer to -r/--revision numbers.
71
72 The following features from `svn log' are supported:
73
74 --revision=<n>[:<n>] - is supported, non-numeric args are not:
75 HEAD, NEXT, BASE, PREV, etc ...
76 -v/--verbose - it's not completely compatible with
77 the --verbose output in svn log, but
78 reasonably close.
79 --limit=<n> - is NOT the same as --max-count,
80 doesn't count merged/excluded commits
81 --incremental - supported
82
83 New features:
84
85 --show-commit - shows the git commit sha1, as well
86 --oneline - our version of --pretty=oneline
87
88 Any other arguments are passed directly to `git log'
89
3289e86e 90'set-tree'::
e8f5d908 91 You should consider using 'dcommit' instead of this command.
3397f9df
EW
92 Commit specified commit or tree objects to SVN. This relies on
93 your imported fetch data being up-to-date. This makes
94 absolutely no attempts to do patching when committing to SVN, it
95 simply overwrites files with those specified in the tree or
96 commit. All merging is assumed to have taken place
97 independently of git-svn functions.
98
0ea4d4c9 99'rebuild'::
3397f9df 100 Not a part of daily usage, but this is a useful command if
0ea4d4c9 101 you've just cloned a repository (using gitlink:git-clone[1]) that was
3397f9df
EW
102 tracked with git-svn. Unfortunately, git-clone does not clone
103 git-svn metadata and the svn working tree that git-svn uses for
104 its operations. This rebuilds the metadata so git-svn can
81c5a0e6
EW
105 resume fetch operations. A Subversion URL may be optionally
106 specified at the command-line if the directory/repository you're
107 tracking has moved or changed protocols.
3397f9df 108
0ea4d4c9 109'show-ignore'::
8f22562c
EW
110 Recursively finds and lists the svn:ignore property on
111 directories. The output is suitable for appending to
112 the $GIT_DIR/info/exclude file.
113
e8f5d908
EW
114'commit-diff'::
115 Commits the diff of two tree-ish arguments from the
23bfbb81 116 command-line. This command is intended for interoperability with
e8f5d908
EW
117 git-svnimport and does not rely on being inside an git-svn
118 init-ed repository. This command takes three arguments, (a) the
119 original tree to diff against, (b) the new tree result, (c) the
120 URL of the target Subversion repository. The final argument
121 (URL) may be omitted if you are working from a git-svn-aware
122 repository (that has been init-ed with git-svn).
45bf473a 123 The -r<revision> option is required for this.
e8f5d908
EW
124
125'graft-branches'::
126 This command attempts to detect merges/branches from already
127 imported history. Techniques used currently include regexes,
128 file copies, and tree-matches). This command generates (or
129 modifies) the $GIT_DIR/info/grafts file. This command is
130 considered experimental, and inherently flawed because
131 merge-tracking in SVN is inherently flawed and inconsistent
132 across different repositories.
133
134'multi-init'::
135 This command supports git-svnimport-like command-line syntax for
136 importing repositories that are layed out as recommended by the
137 SVN folks. This is a bit more tolerant than the git-svnimport
138 command-line syntax and doesn't require the user to figure out
139 where the repository URL ends and where the repository path
140 begins.
141
ae410987
EW
142-T<trunk_subdir>::
143--trunk=<trunk_subdir>::
144-t<tags_subdir>::
145--tags=<tags_subdir>::
146-b<branches_subdir>::
147--branches=<branches_subdir>::
148 These are the command-line options for multi-init. Each of
149 these flags can point to a relative repository path
150 (--tags=project/tags') or a full url
151 (--tags=https://foo.org/project/tags)
152
153--prefix=<prefix>
154 This allows one to specify a prefix which is prepended to the
155 names of remotes. The prefix does not automatically include a
156 trailing slash, so be sure you include one in the argument if
157 that is what you want. This is useful if you wish to track
158 multiple projects that share a common repository.
159
e8f5d908
EW
160'multi-fetch'::
161 This runs fetch on all known SVN branches we're tracking. This
162 will NOT discover new branches (unlike git-svnimport), so
163 multi-init will need to be re-run (it's idempotent).
164
0ea4d4c9
JF
165--
166
3397f9df
EW
167OPTIONS
168-------
0ea4d4c9
JF
169--
170
e8f5d908
EW
171--shared::
172--template=<template_directory>::
173 Only used with the 'init' command.
5c94f87e 174 These are passed directly to gitlink:git-init[1].
e8f5d908 175
3397f9df
EW
176-r <ARG>::
177--revision <ARG>::
3397f9df 178
0ea4d4c9
JF
179Only used with the 'fetch' command.
180
181Takes any valid -r<argument> svn would accept and passes it
182directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax
183is also supported. This is passed directly to svn, see svn
184documentation for more details.
3397f9df 185
0ea4d4c9 186This can allow you to make partial mirrors when running fetch.
3397f9df
EW
187
188-::
189--stdin::
3397f9df 190
3289e86e 191Only used with the 'set-tree' command.
0ea4d4c9
JF
192
193Read a list of commits from stdin and commit them in reverse
194order. Only the leading sha1 is read from each line, so
195git-rev-list --pretty=oneline output can be used.
3397f9df
EW
196
197--rmdir::
3397f9df 198
3289e86e 199Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
0ea4d4c9
JF
200
201Remove directories from the SVN tree if there are no files left
202behind. SVN can version empty directories, and they are not
203removed by default if there are no files left in them. git
204cannot version empty directories. Enabling this flag will make
205the commit to SVN act like git.
3397f9df 206
0ea4d4c9 207repo-config key: svn.rmdir
20b1d700 208
3397f9df
EW
209-e::
210--edit::
3397f9df 211
3289e86e 212Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
3397f9df 213
0ea4d4c9
JF
214Edit the commit message before committing to SVN. This is off by
215default for objects that are commits, and forced on when committing
216tree objects.
217
218repo-config key: svn.edit
20b1d700 219
72942938
EW
220-l<num>::
221--find-copies-harder::
72942938 222
3289e86e 223Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
0ea4d4c9
JF
224
225They are both passed directly to git-diff-tree see
226gitlink:git-diff-tree[1] for more information.
72942938 227
0ea4d4c9
JF
228[verse]
229repo-config key: svn.l
230repo-config key: svn.findcopiesharder
20b1d700 231
81c5a0e6
EW
232-A<filename>::
233--authors-file=<filename>::
234
0ea4d4c9
JF
235Syntax is compatible with the files used by git-svnimport and
236git-cvsimport:
81c5a0e6
EW
237
238------------------------------------------------------------------------
0ea4d4c9 239 loginname = Joe User <user@example.com>
81c5a0e6
EW
240------------------------------------------------------------------------
241
0ea4d4c9
JF
242If this option is specified and git-svn encounters an SVN
243committer name that does not exist in the authors-file, git-svn
244will abort operation. The user will then have to add the
245appropriate entry. Re-running the previous git-svn command
246after the authors-file is modified should continue operation.
81c5a0e6 247
e8f5d908
EW
248repo-config key: svn.authorsfile
249
250-q::
251--quiet::
cec21ca7 252 Make git-svn less verbose.
e8f5d908
EW
253
254--repack[=<n>]::
255--repack-flags=<flags>
256 These should help keep disk usage sane for large fetches
257 with many revisions.
258
259 --repack takes an optional argument for the number of revisions
260 to fetch before repacking. This defaults to repacking every
261 1000 commits fetched if no argument is specified.
262
263 --repack-flags are passed directly to gitlink:git-repack[1].
264
265repo-config key: svn.repack
266repo-config key: svn.repackflags
0ea4d4c9 267
b22d4497
EW
268-m::
269--merge::
270-s<strategy>::
271--strategy=<strategy>::
272
273These are only used with the 'dcommit' command.
274
275Passed directly to git-rebase when using 'dcommit' if a
276'git-reset' cannot be used (see dcommit).
277
278-n::
279--dry-run::
280
281This is only used with the 'dcommit' command.
282
283Print out the series of git arguments that would show
284which diffs would be committed to SVN.
285
0ea4d4c9 286--
81c5a0e6 287
448c81b4
EW
288ADVANCED OPTIONS
289----------------
0ea4d4c9
JF
290--
291
69f0d91e
EW
292-b<refname>::
293--branch <refname>::
3289e86e 294Used with 'fetch', 'dcommit' or 'set-tree'.
69f0d91e 295
0ea4d4c9
JF
296This can be used to join arbitrary git branches to remotes/git-svn
297on new commits where the tree object is equivalent.
69f0d91e 298
0ea4d4c9
JF
299When used with different GIT_SVN_ID values, tags and branches in
300SVN can be tracked this way, as can some merges where the heads
301end up having completely equivalent content. This can even be
302used to track branches across multiple SVN _repositories_.
69f0d91e 303
0ea4d4c9
JF
304This option may be specified multiple times, once for each
305branch.
69f0d91e 306
0ea4d4c9 307repo-config key: svn.branch
20b1d700 308
448c81b4
EW
309-i<GIT_SVN_ID>::
310--id <GIT_SVN_ID>::
0ea4d4c9
JF
311
312This sets GIT_SVN_ID (instead of using the environment). See the
313section on
314'<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>'
315for more information on using GIT_SVN_ID.
316
e8f5d908
EW
317--follow-parent::
318 This is especially helpful when we're tracking a directory
319 that has been moved around within the repository, or if we
320 started tracking a branch and never tracked the trunk it was
321 descended from.
322
e8f5d908
EW
323repo-config key: svn.followparent
324
325--no-metadata::
326 This gets rid of the git-svn-id: lines at the end of every commit.
327
328 With this, you lose the ability to use the rebuild command. If
329 you ever lose your .git/svn/git-svn/.rev_db file, you won't be
330 able to fetch again, either. This is fine for one-shot imports.
331
332 The 'git-svn log' command will not work on repositories using this,
333 either.
334
335repo-config key: svn.nometadata
336
0ea4d4c9 337--
448c81b4 338
3397f9df
EW
339COMPATIBILITY OPTIONS
340---------------------
0ea4d4c9
JF
341--
342
448c81b4 343--upgrade::
0ea4d4c9 344Only used with the 'rebuild' command.
448c81b4 345
0ea4d4c9
JF
346Run this if you used an old version of git-svn that used
347"git-svn-HEAD" instead of "remotes/git-svn" as the branch
348for tracking the remote.
448c81b4 349
f7bae37f
SP
350--ignore-nodate::
351Only used with the 'fetch' command.
352
353By default git-svn will crash if it tries to import a revision
354from SVN which has '(no date)' listed as the date of the revision.
355This is repository corruption on SVN's part, plain and simple.
356But sometimes you really need those revisions anyway.
357
358If supplied git-svn will convert '(no date)' entries to the UNIX
359epoch (midnight on Jan. 1, 1970). Yes, that's probably very wrong.
360SVN was very wrong.
361
0ea4d4c9 362--
20b1d700 363
1d52aba8
EW
364Basic Examples
365~~~~~~~~~~~~~~
3397f9df 366
0d313b2b 367Tracking and contributing to a the trunk of a Subversion-managed project:
3397f9df 368
20b1d700 369------------------------------------------------------------------------
5c94f87e 370# Initialize a repo (like git init):
3397f9df 371 git-svn init http://svn.foo.org/project/trunk
20b1d700 372# Fetch remote revisions:
3397f9df 373 git-svn fetch
20b1d700 374# Create your own branch to hack on:
2beb3cdd 375 git checkout -b my-branch remotes/git-svn
4511c899
EW
376# Do some work, and then commit your new changes to SVN, as well as
377# automatically updating your working HEAD:
378 git-svn dcommit
2e93115e
EW
379# Something is committed to SVN, rebase the latest into your branch:
380 git-svn fetch && git rebase remotes/git-svn
20b1d700 381# Append svn:ignore settings to the default git exclude file:
8f22562c 382 git-svn show-ignore >> .git/info/exclude
20b1d700 383------------------------------------------------------------------------
3397f9df 384
0d313b2b
EW
385Tracking and contributing to an entire Subversion-managed project
386(complete with a trunk, tags and branches):
387See also:
388'<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>'
389
390------------------------------------------------------------------------
5c94f87e 391# Initialize a repo (like git init):
0d313b2b
EW
392 git-svn multi-init http://svn.foo.org/project \
393 -T trunk -b branches -t tags
394# Fetch remote revisions:
395 git-svn multi-fetch
396# Create your own branch of trunk to hack on:
397 git checkout -b my-trunk remotes/trunk
398# Do some work, and then commit your new changes to SVN, as well as
399# automatically updating your working HEAD:
400 git-svn dcommit -i trunk
401# Something has been committed to trunk, rebase the latest into your branch:
402 git-svn multi-fetch && git rebase remotes/trunk
403# Append svn:ignore settings of trunk to the default git exclude file:
404 git-svn show-ignore -i trunk >> .git/info/exclude
405# Check for new branches and tags (no arguments are needed):
406 git-svn multi-init
407------------------------------------------------------------------------
408
2eff1425
EW
409REBASE VS. PULL/MERGE
410---------------------
2e93115e
EW
411
412Originally, git-svn recommended that the remotes/git-svn branch be
2eff1425
EW
413pulled or merged from. This is because the author favored
414'git-svn set-tree B' to commit a single head rather than the
415'git-svn set-tree A..B' notation to commit multiple commits.
416
417If you use 'git-svn set-tree A..B' to commit several diffs and you do
418not have the latest remotes/git-svn merged into my-branch, you should
419use 'git rebase' to update your work branch instead of 'git pull' or
420'git merge'. 'pull/merge' can cause non-linear history to be flattened
421when committing into SVN, which can lead to merge commits reversing
422previous commits in SVN.
2e93115e 423
3397f9df
EW
424DESIGN PHILOSOPHY
425-----------------
426Merge tracking in Subversion is lacking and doing branched development
4511c899
EW
427with Subversion is cumbersome as a result. git-svn does not do
428automated merge/branch tracking by default and leaves it entirely up to
429the user on the git side.
3397f9df 430
0ea4d4c9 431[[tracking-multiple-repos]]
3397f9df
EW
432TRACKING MULTIPLE REPOSITORIES OR BRANCHES
433------------------------------------------
3397f9df
EW
434Because git-svn does not care about relationships between different
435branches or directories in a Subversion repository, git-svn has a simple
436hack to allow it to track an arbitrary number of related _or_ unrelated
4511c899
EW
437SVN repositories via one git repository. Simply use the --id/-i flag or
438set the GIT_SVN_ID environment variable to a name other other than
439"git-svn" (the default) and git-svn will ignore the contents of the
440$GIT_DIR/svn/git-svn directory and instead do all of its work in
441$GIT_DIR/svn/$GIT_SVN_ID for that invocation. The interface branch will
442be remotes/$GIT_SVN_ID, instead of remotes/git-svn. Any
443remotes/$GIT_SVN_ID branch should never be modified by the user outside
444of git-svn commands.
3397f9df 445
0ea4d4c9 446[[fetch-args]]
3397f9df
EW
447ADDITIONAL FETCH ARGUMENTS
448--------------------------
449This is for advanced users, most users should ignore this section.
450
451Unfetched SVN revisions may be imported as children of existing commits
452by specifying additional arguments to 'fetch'. Additional parents may
453optionally be specified in the form of sha1 hex sums at the
454command-line. Unfetched SVN revisions may also be tied to particular
455git commits with the following syntax:
456
0ea4d4c9 457------------------------------------------------
3397f9df 458 svn_revision_number=git_commit_sha1
0ea4d4c9 459------------------------------------------------
3397f9df 460
0ea4d4c9 461This allows you to tie unfetched SVN revision 375 to your current HEAD:
3397f9df 462
0ea4d4c9
JF
463------------------------------------------------
464 git-svn fetch 375=$(git-rev-parse HEAD)
465------------------------------------------------
3397f9df 466
1d52aba8
EW
467If you're tracking a directory that has moved, or otherwise been
468branched or tagged off of another directory in the repository and you
cec21ca7
SG
469care about the full history of the project, then you can use
470the --follow-parent option.
1d52aba8 471
cec21ca7
SG
472------------------------------------------------
473 git-svn fetch --follow-parent
474------------------------------------------------
1d52aba8 475
3397f9df
EW
476BUGS
477----
e8f5d908 478
3397f9df
EW
479We ignore all SVN properties except svn:executable. Too difficult to
480map them since we rely heavily on git write-tree being _exactly_ the
481same on both the SVN and git working trees and I prefer not to clutter
482working trees with metadata files.
483
bbe0c9b8
EW
484Renamed and copied directories are not detected by git and hence not
485tracked when committing to SVN. I do not plan on adding support for
486this as it's quite difficult and time-consuming to get working for all
487the possible corner cases (git doesn't do it, either). Renamed and
488copied files are fully supported if they're similar enough for git to
489detect them.
490
2e93115e
EW
491SEE ALSO
492--------
493gitlink:git-rebase[1]
494
3397f9df
EW
495Author
496------
497Written by Eric Wong <normalperson@yhbt.net>.
498
499Documentation
500-------------
501Written by Eric Wong <normalperson@yhbt.net>.