]>
Commit | Line | Data |
---|---|---|
1 | git-svn(1) | |
2 | ========== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-svn - Bidirectional operation between a Subversion repository and git | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | 'git svn' <command> [options] [arguments] | |
11 | ||
12 | DESCRIPTION | |
13 | ----------- | |
14 | 'git svn' is a simple conduit for changesets between Subversion and git. | |
15 | It provides a bidirectional flow of changes between a Subversion and a git | |
16 | repository. | |
17 | ||
18 | 'git svn' can track a standard Subversion repository, | |
19 | following the common "trunk/branches/tags" layout, with the --stdlayout option. | |
20 | It can also follow branches and tags in any layout with the -T/-t/-b options | |
21 | (see options to 'init' below, and also the 'clone' command). | |
22 | ||
23 | Once tracking a Subversion repository (with any of the above methods), the git | |
24 | repository can be updated from Subversion by the 'fetch' command and | |
25 | Subversion updated from git by the 'dcommit' command. | |
26 | ||
27 | COMMANDS | |
28 | -------- | |
29 | ||
30 | 'init':: | |
31 | Initializes an empty git repository with additional | |
32 | metadata directories for 'git svn'. The Subversion URL | |
33 | may be specified as a command-line argument, or as full | |
34 | URL arguments to -T/-t/-b. Optionally, the target | |
35 | directory to operate on can be specified as a second | |
36 | argument. Normally this command initializes the current | |
37 | directory. | |
38 | ||
39 | -T<trunk_subdir>;; | |
40 | --trunk=<trunk_subdir>;; | |
41 | -t<tags_subdir>;; | |
42 | --tags=<tags_subdir>;; | |
43 | -b<branches_subdir>;; | |
44 | --branches=<branches_subdir>;; | |
45 | -s;; | |
46 | --stdlayout;; | |
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). | |
51 | You can specify more than one --tags and/or --branches options, in case | |
52 | your Subversion repository places tags or branches under multiple paths. | |
53 | The option --stdlayout is | |
54 | a shorthand way of setting trunk,tags,branches as the relative paths, | |
55 | which is the Subversion default. If any of the other options are given | |
56 | as well, they take precedence. | |
57 | --no-metadata;; | |
58 | Set the 'noMetadata' option in the [svn-remote] config. | |
59 | This option is not recommended, please read the 'svn.noMetadata' | |
60 | section of this manpage before using this option. | |
61 | --use-svm-props;; | |
62 | Set the 'useSvmProps' option in the [svn-remote] config. | |
63 | --use-svnsync-props;; | |
64 | Set the 'useSvnsyncProps' option in the [svn-remote] config. | |
65 | --rewrite-root=<URL>;; | |
66 | Set the 'rewriteRoot' option in the [svn-remote] config. | |
67 | --rewrite-uuid=<UUID>;; | |
68 | Set the 'rewriteUUID' option in the [svn-remote] config. | |
69 | --username=<user>;; | |
70 | For transports that SVN handles authentication for (http, | |
71 | https, and plain svn), specify the username. For other | |
72 | transports (eg svn+ssh://), you must include the username in | |
73 | the URL, eg svn+ssh://foo@svn.bar.com/project | |
74 | --prefix=<prefix>;; | |
75 | This allows one to specify a prefix which is prepended | |
76 | to the names of remotes if trunk/branches/tags are | |
77 | specified. The prefix does not automatically include a | |
78 | trailing slash, so be sure you include one in the | |
79 | argument if that is what you want. If --branches/-b is | |
80 | specified, the prefix must include a trailing slash. | |
81 | Setting a prefix is useful if you wish to track multiple | |
82 | projects that share a common repository. | |
83 | --ignore-paths=<regex>;; | |
84 | When passed to 'init' or 'clone' this regular expression will | |
85 | be preserved as a config key. See 'fetch' for a description | |
86 | of '--ignore-paths'. | |
87 | --no-minimize-url;; | |
88 | When tracking multiple directories (using --stdlayout, | |
89 | --branches, or --tags options), git svn will attempt to connect | |
90 | to the root (or highest allowed level) of the Subversion | |
91 | repository. This default allows better tracking of history if | |
92 | entire projects are moved within a repository, but may cause | |
93 | issues on repositories where read access restrictions are in | |
94 | place. Passing '--no-minimize-url' will allow git svn to | |
95 | accept URLs as-is without attempting to connect to a higher | |
96 | level directory. This option is off by default when only | |
97 | one URL/branch is tracked (it would do little good). | |
98 | ||
99 | 'fetch':: | |
100 | Fetch unfetched revisions from the Subversion remote we are | |
101 | tracking. The name of the [svn-remote "..."] section in the | |
102 | .git/config file may be specified as an optional command-line | |
103 | argument. | |
104 | ||
105 | --localtime;; | |
106 | Store Git commit times in the local timezone instead of UTC. This | |
107 | makes 'git log' (even without --date=local) show the same times | |
108 | that `svn log` would in the local timezone. | |
109 | + | |
110 | This doesn't interfere with interoperating with the Subversion | |
111 | repository you cloned from, but if you wish for your local Git | |
112 | repository to be able to interoperate with someone else's local Git | |
113 | repository, either don't use this option or you should both use it in | |
114 | the same local timezone. | |
115 | ||
116 | --parent;; | |
117 | Fetch only from the SVN parent of the current HEAD. | |
118 | ||
119 | --ignore-paths=<regex>;; | |
120 | This allows one to specify a Perl regular expression that will | |
121 | cause skipping of all matching paths from checkout from SVN. | |
122 | The '--ignore-paths' option should match for every 'fetch' | |
123 | (including automatic fetches due to 'clone', 'dcommit', | |
124 | 'rebase', etc) on a given repository. | |
125 | + | |
126 | [verse] | |
127 | config key: svn-remote.<name>.ignore-paths | |
128 | + | |
129 | If the ignore-paths config key is set and the command line option is | |
130 | also given, both regular expressions will be used. | |
131 | + | |
132 | Examples: | |
133 | + | |
134 | -- | |
135 | Skip "doc*" directory for every fetch;; | |
136 | + | |
137 | ------------------------------------------------------------------------ | |
138 | --ignore-paths="^doc" | |
139 | ------------------------------------------------------------------------ | |
140 | ||
141 | Skip "branches" and "tags" of first level directories;; | |
142 | + | |
143 | ------------------------------------------------------------------------ | |
144 | --ignore-paths="^[^/]+/(?:branches|tags)" | |
145 | ------------------------------------------------------------------------ | |
146 | -- | |
147 | ||
148 | --use-log-author;; | |
149 | When retrieving svn commits into git (as part of fetch, rebase, or | |
150 | dcommit operations), look for the first From: or Signed-off-by: line | |
151 | in the log message and use that as the author string. | |
152 | --add-author-from;; | |
153 | When committing to svn from git (as part of commit or dcommit | |
154 | operations), if the existing log message doesn't already have a | |
155 | From: or Signed-off-by: line, append a From: line based on the | |
156 | git commit's author string. If you use this, then --use-log-author | |
157 | will retrieve a valid author string for all commits. | |
158 | ||
159 | 'clone':: | |
160 | Runs 'init' and 'fetch'. It will automatically create a | |
161 | directory based on the basename of the URL passed to it; | |
162 | or if a second argument is passed; it will create a directory | |
163 | and work within that. It accepts all arguments that the | |
164 | 'init' and 'fetch' commands accept; with the exception of | |
165 | '--fetch-all' and '--parent'. After a repository is cloned, | |
166 | the 'fetch' command will be able to update revisions without | |
167 | affecting the working tree; and the 'rebase' command will be | |
168 | able to update the working tree with the latest changes. | |
169 | ||
170 | 'rebase':: | |
171 | This fetches revisions from the SVN parent of the current HEAD | |
172 | and rebases the current (uncommitted to SVN) work against it. | |
173 | + | |
174 | This works similarly to `svn update` or 'git pull' except that | |
175 | it preserves linear history with 'git rebase' instead of | |
176 | 'git merge' for ease of dcommitting with 'git svn'. | |
177 | + | |
178 | This accepts all options that 'git svn fetch' and 'git rebase' | |
179 | accept. However, '--fetch-all' only fetches from the current | |
180 | [svn-remote], and not all [svn-remote] definitions. | |
181 | + | |
182 | Like 'git rebase'; this requires that the working tree be clean | |
183 | and have no uncommitted changes. | |
184 | ||
185 | -l;; | |
186 | --local;; | |
187 | Do not fetch remotely; only run 'git rebase' against the | |
188 | last fetched commit from the upstream SVN. | |
189 | ||
190 | 'dcommit':: | |
191 | Commit each diff from a specified head directly to the SVN | |
192 | repository, and then rebase or reset (depending on whether or | |
193 | not there is a diff between SVN and head). This will create | |
194 | a revision in SVN for each commit in git. | |
195 | It is recommended that you run 'git svn' fetch and rebase (not | |
196 | pull or merge) your commits against the latest changes in the | |
197 | SVN repository. | |
198 | An optional revision or branch argument may be specified, and | |
199 | causes 'git svn' to do all work on that revision/branch | |
200 | instead of HEAD. | |
201 | This is advantageous over 'set-tree' (below) because it produces | |
202 | cleaner, more linear history. | |
203 | + | |
204 | --no-rebase;; | |
205 | After committing, do not rebase or reset. | |
206 | --commit-url <URL>;; | |
207 | Commit to this SVN URL (the full path). This is intended to | |
208 | allow existing 'git svn' repositories created with one transport | |
209 | method (e.g. `svn://` or `http://` for anonymous read) to be | |
210 | reused if a user is later given access to an alternate transport | |
211 | method (e.g. `svn+ssh://` or `https://`) for commit. | |
212 | + | |
213 | [verse] | |
214 | config key: svn-remote.<name>.commiturl | |
215 | config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options) | |
216 | + | |
217 | Using this option for any other purpose (don't ask) is very strongly | |
218 | discouraged. | |
219 | ||
220 | 'branch':: | |
221 | Create a branch in the SVN repository. | |
222 | ||
223 | -m;; | |
224 | --message;; | |
225 | Allows to specify the commit message. | |
226 | ||
227 | -t;; | |
228 | --tag;; | |
229 | Create a tag by using the tags_subdir instead of the branches_subdir | |
230 | specified during git svn init. | |
231 | ||
232 | -d;; | |
233 | --destination;; | |
234 | If more than one --branches (or --tags) option was given to the 'init' | |
235 | or 'clone' command, you must provide the location of the branch (or | |
236 | tag) you wish to create in the SVN repository. The value of this | |
237 | option must match one of the paths specified by a --branches (or | |
238 | --tags) option. You can see these paths with the commands | |
239 | + | |
240 | git config --get-all svn-remote.<name>.branches | |
241 | git config --get-all svn-remote.<name>.tags | |
242 | + | |
243 | where <name> is the name of the SVN repository as specified by the -R option to | |
244 | 'init' (or "svn" by default). | |
245 | ||
246 | --username;; | |
247 | Specify the SVN username to perform the commit as. This option overrides | |
248 | the 'username' configuration property. | |
249 | ||
250 | --commit-url;; | |
251 | Use the specified URL to connect to the destination Subversion | |
252 | repository. This is useful in cases where the source SVN | |
253 | repository is read-only. This option overrides configuration | |
254 | property 'commiturl'. | |
255 | + | |
256 | git config --get-all svn-remote.<name>.commiturl | |
257 | + | |
258 | ||
259 | 'tag':: | |
260 | Create a tag in the SVN repository. This is a shorthand for | |
261 | 'branch -t'. | |
262 | ||
263 | 'log':: | |
264 | This should make it easy to look up svn log messages when svn | |
265 | users refer to -r/--revision numbers. | |
266 | + | |
267 | The following features from `svn log' are supported: | |
268 | + | |
269 | -- | |
270 | -r <n>[:<n>];; | |
271 | --revision=<n>[:<n>];; | |
272 | is supported, non-numeric args are not: | |
273 | HEAD, NEXT, BASE, PREV, etc ... | |
274 | -v;; | |
275 | --verbose;; | |
276 | it's not completely compatible with the --verbose | |
277 | output in svn log, but reasonably close. | |
278 | --limit=<n>;; | |
279 | is NOT the same as --max-count, doesn't count | |
280 | merged/excluded commits | |
281 | --incremental;; | |
282 | supported | |
283 | -- | |
284 | + | |
285 | New features: | |
286 | + | |
287 | -- | |
288 | --show-commit;; | |
289 | shows the git commit sha1, as well | |
290 | --oneline;; | |
291 | our version of --pretty=oneline | |
292 | -- | |
293 | + | |
294 | NOTE: SVN itself only stores times in UTC and nothing else. The regular svn | |
295 | client converts the UTC time to the local time (or based on the TZ= | |
296 | environment). This command has the same behaviour. | |
297 | + | |
298 | Any other arguments are passed directly to 'git log' | |
299 | ||
300 | 'blame':: | |
301 | Show what revision and author last modified each line of a file. The | |
302 | output of this mode is format-compatible with the output of | |
303 | `svn blame' by default. Like the SVN blame command, | |
304 | local uncommitted changes in the working copy are ignored; | |
305 | the version of the file in the HEAD revision is annotated. Unknown | |
306 | arguments are passed directly to 'git blame'. | |
307 | + | |
308 | --git-format;; | |
309 | Produce output in the same format as 'git blame', but with | |
310 | SVN revision numbers instead of git commit hashes. In this mode, | |
311 | changes that haven't been committed to SVN (including local | |
312 | working-copy edits) are shown as revision 0. | |
313 | ||
314 | 'find-rev':: | |
315 | When given an SVN revision number of the form 'rN', returns the | |
316 | corresponding git commit hash (this can optionally be followed by a | |
317 | tree-ish to specify which branch should be searched). When given a | |
318 | tree-ish, returns the corresponding SVN revision number. | |
319 | ||
320 | 'set-tree':: | |
321 | You should consider using 'dcommit' instead of this command. | |
322 | Commit specified commit or tree objects to SVN. This relies on | |
323 | your imported fetch data being up-to-date. This makes | |
324 | absolutely no attempts to do patching when committing to SVN, it | |
325 | simply overwrites files with those specified in the tree or | |
326 | commit. All merging is assumed to have taken place | |
327 | independently of 'git svn' functions. | |
328 | ||
329 | 'create-ignore':: | |
330 | Recursively finds the svn:ignore property on directories and | |
331 | creates matching .gitignore files. The resulting files are staged to | |
332 | be committed, but are not committed. Use -r/--revision to refer to a | |
333 | specific revision. | |
334 | ||
335 | 'show-ignore':: | |
336 | Recursively finds and lists the svn:ignore property on | |
337 | directories. The output is suitable for appending to | |
338 | the $GIT_DIR/info/exclude file. | |
339 | ||
340 | 'mkdirs':: | |
341 | Attempts to recreate empty directories that core git cannot track | |
342 | based on information in $GIT_DIR/svn/<refname>/unhandled.log files. | |
343 | Empty directories are automatically recreated when using | |
344 | "git svn clone" and "git svn rebase", so "mkdirs" is intended | |
345 | for use after commands like "git checkout" or "git reset". | |
346 | ||
347 | 'commit-diff':: | |
348 | Commits the diff of two tree-ish arguments from the | |
349 | command-line. This command does not rely on being inside an `git svn | |
350 | init`-ed repository. This command takes three arguments, (a) the | |
351 | original tree to diff against, (b) the new tree result, (c) the | |
352 | URL of the target Subversion repository. The final argument | |
353 | (URL) may be omitted if you are working from a 'git svn'-aware | |
354 | repository (that has been `init`-ed with 'git svn'). | |
355 | The -r<revision> option is required for this. | |
356 | ||
357 | 'info':: | |
358 | Shows information about a file or directory similar to what | |
359 | `svn info' provides. Does not currently support a -r/--revision | |
360 | argument. Use the --url option to output only the value of the | |
361 | 'URL:' field. | |
362 | ||
363 | 'proplist':: | |
364 | Lists the properties stored in the Subversion repository about a | |
365 | given file or directory. Use -r/--revision to refer to a specific | |
366 | Subversion revision. | |
367 | ||
368 | 'propget':: | |
369 | Gets the Subversion property given as the first argument, for a | |
370 | file. A specific revision can be specified with -r/--revision. | |
371 | ||
372 | 'show-externals':: | |
373 | Shows the Subversion externals. Use -r/--revision to specify a | |
374 | specific revision. | |
375 | ||
376 | 'gc':: | |
377 | Compress $GIT_DIR/svn/<refname>/unhandled.log files in .git/svn | |
378 | and remove $GIT_DIR/svn/<refname>index files in .git/svn. | |
379 | ||
380 | 'reset':: | |
381 | Undoes the effects of 'fetch' back to the specified revision. | |
382 | This allows you to re-'fetch' an SVN revision. Normally the | |
383 | contents of an SVN revision should never change and 'reset' | |
384 | should not be necessary. However, if SVN permissions change, | |
385 | or if you alter your --ignore-paths option, a 'fetch' may fail | |
386 | with "not found in commit" (file not previously visible) or | |
387 | "checksum mismatch" (missed a modification). If the problem | |
388 | file cannot be ignored forever (with --ignore-paths) the only | |
389 | way to repair the repo is to use 'reset'. | |
390 | + | |
391 | Only the rev_map and refs/remotes/git-svn are changed. Follow 'reset' | |
392 | with a 'fetch' and then 'git reset' or 'git rebase' to move local | |
393 | branches onto the new tree. | |
394 | ||
395 | -r <n>;; | |
396 | --revision=<n>;; | |
397 | Specify the most recent revision to keep. All later revisions | |
398 | are discarded. | |
399 | -p;; | |
400 | --parent;; | |
401 | Discard the specified revision as well, keeping the nearest | |
402 | parent instead. | |
403 | Example:;; | |
404 | Assume you have local changes in "master", but you need to refetch "r2". | |
405 | + | |
406 | ------------ | |
407 | r1---r2---r3 remotes/git-svn | |
408 | \ | |
409 | A---B master | |
410 | ------------ | |
411 | + | |
412 | Fix the ignore-paths or SVN permissions problem that caused "r2" to | |
413 | be incomplete in the first place. Then: | |
414 | + | |
415 | [verse] | |
416 | git svn reset -r2 -p | |
417 | git svn fetch | |
418 | + | |
419 | ------------ | |
420 | r1---r2'--r3' remotes/git-svn | |
421 | \ | |
422 | r2---r3---A---B master | |
423 | ------------ | |
424 | + | |
425 | Then fixup "master" with 'git rebase'. | |
426 | Do NOT use 'git merge' or your history will not be compatible with a | |
427 | future 'dcommit'! | |
428 | + | |
429 | [verse] | |
430 | git rebase --onto remotes/git-svn A^ master | |
431 | + | |
432 | ------------ | |
433 | r1---r2'--r3' remotes/git-svn | |
434 | \ | |
435 | A'--B' master | |
436 | ------------ | |
437 | ||
438 | OPTIONS | |
439 | ------- | |
440 | ||
441 | --shared[=(false|true|umask|group|all|world|everybody)]:: | |
442 | --template=<template_directory>:: | |
443 | Only used with the 'init' command. | |
444 | These are passed directly to 'git init'. | |
445 | ||
446 | -r <arg>:: | |
447 | --revision <arg>:: | |
448 | Used with the 'fetch' command. | |
449 | + | |
450 | This allows revision ranges for partial/cauterized history | |
451 | to be supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges), | |
452 | $NUMBER:HEAD, and BASE:$NUMBER are all supported. | |
453 | + | |
454 | This can allow you to make partial mirrors when running fetch; | |
455 | but is generally not recommended because history will be skipped | |
456 | and lost. | |
457 | ||
458 | -:: | |
459 | --stdin:: | |
460 | Only used with the 'set-tree' command. | |
461 | + | |
462 | Read a list of commits from stdin and commit them in reverse | |
463 | order. Only the leading sha1 is read from each line, so | |
464 | 'git rev-list --pretty=oneline' output can be used. | |
465 | ||
466 | --rmdir:: | |
467 | Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. | |
468 | + | |
469 | Remove directories from the SVN tree if there are no files left | |
470 | behind. SVN can version empty directories, and they are not | |
471 | removed by default if there are no files left in them. git | |
472 | cannot version empty directories. Enabling this flag will make | |
473 | the commit to SVN act like git. | |
474 | + | |
475 | [verse] | |
476 | config key: svn.rmdir | |
477 | ||
478 | -e:: | |
479 | --edit:: | |
480 | Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. | |
481 | + | |
482 | Edit the commit message before committing to SVN. This is off by | |
483 | default for objects that are commits, and forced on when committing | |
484 | tree objects. | |
485 | + | |
486 | [verse] | |
487 | config key: svn.edit | |
488 | ||
489 | -l<num>:: | |
490 | --find-copies-harder:: | |
491 | Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. | |
492 | + | |
493 | They are both passed directly to 'git diff-tree'; see | |
494 | linkgit:git-diff-tree[1] for more information. | |
495 | + | |
496 | [verse] | |
497 | config key: svn.l | |
498 | config key: svn.findcopiesharder | |
499 | ||
500 | -A<filename>:: | |
501 | --authors-file=<filename>:: | |
502 | Syntax is compatible with the file used by 'git cvsimport': | |
503 | + | |
504 | ------------------------------------------------------------------------ | |
505 | loginname = Joe User <user@example.com> | |
506 | ------------------------------------------------------------------------ | |
507 | + | |
508 | If this option is specified and 'git svn' encounters an SVN | |
509 | committer name that does not exist in the authors-file, 'git svn' | |
510 | will abort operation. The user will then have to add the | |
511 | appropriate entry. Re-running the previous 'git svn' command | |
512 | after the authors-file is modified should continue operation. | |
513 | + | |
514 | [verse] | |
515 | config key: svn.authorsfile | |
516 | ||
517 | --authors-prog=<filename>:: | |
518 | If this option is specified, for each SVN committer name that | |
519 | does not exist in the authors file, the given file is executed | |
520 | with the committer name as the first argument. The program is | |
521 | expected to return a single line of the form "Name <email>", | |
522 | which will be treated as if included in the authors file. | |
523 | ||
524 | -q:: | |
525 | --quiet:: | |
526 | Make 'git svn' less verbose. Specify a second time to make it | |
527 | even less verbose. | |
528 | ||
529 | --repack[=<n>]:: | |
530 | --repack-flags=<flags>:: | |
531 | These should help keep disk usage sane for large fetches with | |
532 | many revisions. | |
533 | + | |
534 | --repack takes an optional argument for the number of revisions | |
535 | to fetch before repacking. This defaults to repacking every | |
536 | 1000 commits fetched if no argument is specified. | |
537 | + | |
538 | --repack-flags are passed directly to 'git repack'. | |
539 | + | |
540 | [verse] | |
541 | config key: svn.repack | |
542 | config key: svn.repackflags | |
543 | ||
544 | -m:: | |
545 | --merge:: | |
546 | -s<strategy>:: | |
547 | --strategy=<strategy>:: | |
548 | These are only used with the 'dcommit' and 'rebase' commands. | |
549 | + | |
550 | Passed directly to 'git rebase' when using 'dcommit' if a | |
551 | 'git reset' cannot be used (see 'dcommit'). | |
552 | ||
553 | -n:: | |
554 | --dry-run:: | |
555 | This can be used with the 'dcommit', 'rebase', 'branch' and | |
556 | 'tag' commands. | |
557 | + | |
558 | For 'dcommit', print out the series of git arguments that would show | |
559 | which diffs would be committed to SVN. | |
560 | + | |
561 | For 'rebase', display the local branch associated with the upstream svn | |
562 | repository associated with the current branch and the URL of svn | |
563 | repository that will be fetched from. | |
564 | + | |
565 | For 'branch' and 'tag', display the urls that will be used for copying when | |
566 | creating the branch or tag. | |
567 | ||
568 | ||
569 | ADVANCED OPTIONS | |
570 | ---------------- | |
571 | ||
572 | -i<GIT_SVN_ID>:: | |
573 | --id <GIT_SVN_ID>:: | |
574 | This sets GIT_SVN_ID (instead of using the environment). This | |
575 | allows the user to override the default refname to fetch from | |
576 | when tracking a single URL. The 'log' and 'dcommit' commands | |
577 | no longer require this switch as an argument. | |
578 | ||
579 | -R<remote name>:: | |
580 | --svn-remote <remote name>:: | |
581 | Specify the [svn-remote "<remote name>"] section to use, | |
582 | this allows SVN multiple repositories to be tracked. | |
583 | Default: "svn" | |
584 | ||
585 | --follow-parent:: | |
586 | This is especially helpful when we're tracking a directory | |
587 | that has been moved around within the repository, or if we | |
588 | started tracking a branch and never tracked the trunk it was | |
589 | descended from. This feature is enabled by default, use | |
590 | --no-follow-parent to disable it. | |
591 | + | |
592 | [verse] | |
593 | config key: svn.followparent | |
594 | ||
595 | CONFIG FILE-ONLY OPTIONS | |
596 | ------------------------ | |
597 | ||
598 | svn.noMetadata:: | |
599 | svn-remote.<name>.noMetadata:: | |
600 | This gets rid of the 'git-svn-id:' lines at the end of every commit. | |
601 | + | |
602 | This option can only be used for one-shot imports as 'git svn' | |
603 | will not be able to fetch again without metadata. Additionally, | |
604 | if you lose your .git/svn/**/.rev_map.* files, 'git svn' will not | |
605 | be able to rebuild them. | |
606 | + | |
607 | The 'git svn log' command will not work on repositories using | |
608 | this, either. Using this conflicts with the 'useSvmProps' | |
609 | option for (hopefully) obvious reasons. | |
610 | + | |
611 | This option is NOT recommended as it makes it difficult to track down | |
612 | old references to SVN revision numbers in existing documentation, bug | |
613 | reports and archives. If you plan to eventually migrate from SVN to git | |
614 | and are certain about dropping SVN history, consider | |
615 | linkgit:git-filter-branch[1] instead. filter-branch also allows | |
616 | reformatting of metadata for ease-of-reading and rewriting authorship | |
617 | info for non-"svn.authorsFile" users. | |
618 | ||
619 | svn.useSvmProps:: | |
620 | svn-remote.<name>.useSvmProps:: | |
621 | This allows 'git svn' to re-map repository URLs and UUIDs from | |
622 | mirrors created using SVN::Mirror (or svk) for metadata. | |
623 | + | |
624 | If an SVN revision has a property, "svm:headrev", it is likely | |
625 | that the revision was created by SVN::Mirror (also used by SVK). | |
626 | The property contains a repository UUID and a revision. We want | |
627 | to make it look like we are mirroring the original URL, so | |
628 | introduce a helper function that returns the original identity | |
629 | URL and UUID, and use it when generating metadata in commit | |
630 | messages. | |
631 | ||
632 | svn.useSvnsyncProps:: | |
633 | svn-remote.<name>.useSvnsyncprops:: | |
634 | Similar to the useSvmProps option; this is for users | |
635 | of the svnsync(1) command distributed with SVN 1.4.x and | |
636 | later. | |
637 | ||
638 | svn-remote.<name>.rewriteRoot:: | |
639 | This allows users to create repositories from alternate | |
640 | URLs. For example, an administrator could run 'git svn' on the | |
641 | server locally (accessing via file://) but wish to distribute | |
642 | the repository with a public http:// or svn:// URL in the | |
643 | metadata so users of it will see the public URL. | |
644 | ||
645 | svn-remote.<name>.rewriteUUID:: | |
646 | Similar to the useSvmProps option; this is for users who need | |
647 | to remap the UUID manually. This may be useful in situations | |
648 | where the original UUID is not available via either useSvmProps | |
649 | or useSvnsyncProps. | |
650 | ||
651 | svn.brokenSymlinkWorkaround:: | |
652 | This disables potentially expensive checks to workaround | |
653 | broken symlinks checked into SVN by broken clients. Set this | |
654 | option to "false" if you track a SVN repository with many | |
655 | empty blobs that are not symlinks. This option may be changed | |
656 | while 'git svn' is running and take effect on the next | |
657 | revision fetched. If unset, 'git svn' assumes this option to | |
658 | be "true". | |
659 | ||
660 | svn.pathnameencoding:: | |
661 | This instructs git svn to recode pathnames to a given encoding. | |
662 | It can be used by windows users and by those who work in non-utf8 | |
663 | locales to avoid corrupted file names with non-ASCII characters. | |
664 | Valid encodings are the ones supported by Perl's Encode module. | |
665 | ||
666 | Since the noMetadata, rewriteRoot, rewriteUUID, useSvnsyncProps and useSvmProps | |
667 | options all affect the metadata generated and used by 'git svn'; they | |
668 | *must* be set in the configuration file before any history is imported | |
669 | and these settings should never be changed once they are set. | |
670 | ||
671 | Additionally, only one of these options can be used per svn-remote | |
672 | section because they affect the 'git-svn-id:' metadata line, except | |
673 | for rewriteRoot and rewriteUUID which can be used together. | |
674 | ||
675 | ||
676 | BASIC EXAMPLES | |
677 | -------------- | |
678 | ||
679 | Tracking and contributing to the trunk of a Subversion-managed project: | |
680 | ||
681 | ------------------------------------------------------------------------ | |
682 | # Clone a repo (like git clone): | |
683 | git svn clone http://svn.example.com/project/trunk | |
684 | # Enter the newly cloned directory: | |
685 | cd trunk | |
686 | # You should be on master branch, double-check with 'git branch' | |
687 | git branch | |
688 | # Do some work and commit locally to git: | |
689 | git commit ... | |
690 | # Something is committed to SVN, rebase your local changes against the | |
691 | # latest changes in SVN: | |
692 | git svn rebase | |
693 | # Now commit your changes (that were committed previously using git) to SVN, | |
694 | # as well as automatically updating your working HEAD: | |
695 | git svn dcommit | |
696 | # Append svn:ignore settings to the default git exclude file: | |
697 | git svn show-ignore >> .git/info/exclude | |
698 | ------------------------------------------------------------------------ | |
699 | ||
700 | Tracking and contributing to an entire Subversion-managed project | |
701 | (complete with a trunk, tags and branches): | |
702 | ||
703 | ------------------------------------------------------------------------ | |
704 | # Clone a repo (like git clone): | |
705 | git svn clone http://svn.example.com/project -T trunk -b branches -t tags | |
706 | # View all branches and tags you have cloned: | |
707 | git branch -r | |
708 | # Create a new branch in SVN | |
709 | git svn branch waldo | |
710 | # Reset your master to trunk (or any other branch, replacing 'trunk' | |
711 | # with the appropriate name): | |
712 | git reset --hard remotes/trunk | |
713 | # You may only dcommit to one branch/tag/trunk at a time. The usage | |
714 | # of dcommit/rebase/show-ignore should be the same as above. | |
715 | ------------------------------------------------------------------------ | |
716 | ||
717 | The initial 'git svn clone' can be quite time-consuming | |
718 | (especially for large Subversion repositories). If multiple | |
719 | people (or one person with multiple machines) want to use | |
720 | 'git svn' to interact with the same Subversion repository, you can | |
721 | do the initial 'git svn clone' to a repository on a server and | |
722 | have each person clone that repository with 'git clone': | |
723 | ||
724 | ------------------------------------------------------------------------ | |
725 | # Do the initial import on a server | |
726 | ssh server "cd /pub && git svn clone http://svn.example.com/project | |
727 | # Clone locally - make sure the refs/remotes/ space matches the server | |
728 | mkdir project | |
729 | cd project | |
730 | git init | |
731 | git remote add origin server:/pub/project | |
732 | git config --replace-all remote.origin.fetch '+refs/remotes/*:refs/remotes/*' | |
733 | git fetch | |
734 | # Prevent fetch/pull from remote git server in the future, | |
735 | # we only want to use git svn for future updates | |
736 | git config --remove-section remote.origin | |
737 | # Create a local branch from one of the branches just fetched | |
738 | git checkout -b master FETCH_HEAD | |
739 | # Initialize 'git svn' locally (be sure to use the same URL and -T/-b/-t options as were used on server) | |
740 | git svn init http://svn.example.com/project | |
741 | # Pull the latest changes from Subversion | |
742 | git svn rebase | |
743 | ------------------------------------------------------------------------ | |
744 | ||
745 | REBASE VS. PULL/MERGE | |
746 | --------------------- | |
747 | ||
748 | Originally, 'git svn' recommended that the 'remotes/git-svn' branch be | |
749 | pulled or merged from. This is because the author favored | |
750 | `git svn set-tree B` to commit a single head rather than the | |
751 | `git svn set-tree A..B` notation to commit multiple commits. | |
752 | ||
753 | If you use `git svn set-tree A..B` to commit several diffs and you do | |
754 | not have the latest remotes/git-svn merged into my-branch, you should | |
755 | use `git svn rebase` to update your work branch instead of `git pull` or | |
756 | `git merge`. `pull`/`merge` can cause non-linear history to be flattened | |
757 | when committing into SVN, which can lead to merge commits reversing | |
758 | previous commits in SVN. | |
759 | ||
760 | DESIGN PHILOSOPHY | |
761 | ----------------- | |
762 | Merge tracking in Subversion is lacking and doing branched development | |
763 | with Subversion can be cumbersome as a result. While 'git svn' can track | |
764 | copy history (including branches and tags) for repositories adopting a | |
765 | standard layout, it cannot yet represent merge history that happened | |
766 | inside git back upstream to SVN users. Therefore it is advised that | |
767 | users keep history as linear as possible inside git to ease | |
768 | compatibility with SVN (see the CAVEATS section below). | |
769 | ||
770 | CAVEATS | |
771 | ------- | |
772 | ||
773 | For the sake of simplicity and interoperating with a less-capable system | |
774 | (SVN), it is recommended that all 'git svn' users clone, fetch and dcommit | |
775 | directly from the SVN server, and avoid all 'git clone'/'pull'/'merge'/'push' | |
776 | operations between git repositories and branches. The recommended | |
777 | method of exchanging code between git branches and users is | |
778 | 'git format-patch' and 'git am', or just 'dcommit'ing to the SVN repository. | |
779 | ||
780 | Running 'git merge' or 'git pull' is NOT recommended on a branch you | |
781 | plan to 'dcommit' from. Subversion does not represent merges in any | |
782 | reasonable or useful fashion; so users using Subversion cannot see any | |
783 | merges you've made. Furthermore, if you merge or pull from a git branch | |
784 | that is a mirror of an SVN branch, 'dcommit' may commit to the wrong | |
785 | branch. | |
786 | ||
787 | If you do merge, note the following rule: 'git svn dcommit' will | |
788 | attempt to commit on top of the SVN commit named in | |
789 | ------------------------------------------------------------------------ | |
790 | git log --grep=^git-svn-id: --first-parent -1 | |
791 | ------------------------------------------------------------------------ | |
792 | You 'must' therefore ensure that the most recent commit of the branch | |
793 | you want to dcommit to is the 'first' parent of the merge. Chaos will | |
794 | ensue otherwise, especially if the first parent is an older commit on | |
795 | the same SVN branch. | |
796 | ||
797 | 'git clone' does not clone branches under the refs/remotes/ hierarchy or | |
798 | any 'git svn' metadata, or config. So repositories created and managed with | |
799 | using 'git svn' should use 'rsync' for cloning, if cloning is to be done | |
800 | at all. | |
801 | ||
802 | Since 'dcommit' uses rebase internally, any git branches you 'git push' to | |
803 | before 'dcommit' on will require forcing an overwrite of the existing ref | |
804 | on the remote repository. This is generally considered bad practice, | |
805 | see the linkgit:git-push[1] documentation for details. | |
806 | ||
807 | Do not use the --amend option of linkgit:git-commit[1] on a change you've | |
808 | already dcommitted. It is considered bad practice to --amend commits | |
809 | you've already pushed to a remote repository for other users, and | |
810 | dcommit with SVN is analogous to that. | |
811 | ||
812 | When using multiple --branches or --tags, 'git svn' does not automatically | |
813 | handle name collisions (for example, if two branches from different paths have | |
814 | the same name, or if a branch and a tag have the same name). In these cases, | |
815 | use 'init' to set up your git repository then, before your first 'fetch', edit | |
816 | the .git/config file so that the branches and tags are associated with | |
817 | different name spaces. For example: | |
818 | ||
819 | branches = stable/*:refs/remotes/svn/stable/* | |
820 | branches = debug/*:refs/remotes/svn/debug/* | |
821 | ||
822 | BUGS | |
823 | ---- | |
824 | ||
825 | We ignore all SVN properties except svn:executable. Any unhandled | |
826 | properties are logged to $GIT_DIR/svn/<refname>/unhandled.log | |
827 | ||
828 | Renamed and copied directories are not detected by git and hence not | |
829 | tracked when committing to SVN. I do not plan on adding support for | |
830 | this as it's quite difficult and time-consuming to get working for all | |
831 | the possible corner cases (git doesn't do it, either). Committing | |
832 | renamed and copied files are fully supported if they're similar enough | |
833 | for git to detect them. | |
834 | ||
835 | CONFIGURATION | |
836 | ------------- | |
837 | ||
838 | 'git svn' stores [svn-remote] configuration information in the | |
839 | repository .git/config file. It is similar the core git | |
840 | [remote] sections except 'fetch' keys do not accept glob | |
841 | arguments; but they are instead handled by the 'branches' | |
842 | and 'tags' keys. Since some SVN repositories are oddly | |
843 | configured with multiple projects glob expansions such those | |
844 | listed below are allowed: | |
845 | ||
846 | ------------------------------------------------------------------------ | |
847 | [svn-remote "project-a"] | |
848 | url = http://server.org/svn | |
849 | fetch = trunk/project-a:refs/remotes/project-a/trunk | |
850 | branches = branches/*/project-a:refs/remotes/project-a/branches/* | |
851 | tags = tags/*/project-a:refs/remotes/project-a/tags/* | |
852 | ------------------------------------------------------------------------ | |
853 | ||
854 | Keep in mind that the '\*' (asterisk) wildcard of the local ref | |
855 | (right of the ':') *must* be the farthest right path component; | |
856 | however the remote wildcard may be anywhere as long as it's an | |
857 | independent path component (surrounded by '/' or EOL). This | |
858 | type of configuration is not automatically created by 'init' and | |
859 | should be manually entered with a text-editor or using 'git config'. | |
860 | ||
861 | It is also possible to fetch a subset of branches or tags by using a | |
862 | comma-separated list of names within braces. For example: | |
863 | ||
864 | ------------------------------------------------------------------------ | |
865 | [svn-remote "huge-project"] | |
866 | url = http://server.org/svn | |
867 | fetch = trunk/src:refs/remotes/trunk | |
868 | branches = branches/{red,green}/src:refs/remotes/branches/* | |
869 | tags = tags/{1.0,2.0}/src:refs/remotes/tags/* | |
870 | ------------------------------------------------------------------------ | |
871 | ||
872 | Note that git-svn keeps track of the highest revision in which a branch | |
873 | or tag has appeared. If the subset of branches or tags is changed after | |
874 | fetching, then .git/svn/.metadata must be manually edited to remove (or | |
875 | reset) branches-maxRev and/or tags-maxRev as appropriate. | |
876 | ||
877 | SEE ALSO | |
878 | -------- | |
879 | linkgit:git-rebase[1] |