]>
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 | [verse] | |
11 | 'git svn' <command> [<options>] [<arguments>] | |
12 | ||
13 | DESCRIPTION | |
14 | ----------- | |
15 | 'git svn' is a simple conduit for changesets between Subversion and Git. | |
16 | It provides a bidirectional flow of changes between a Subversion and a Git | |
17 | repository. | |
18 | ||
19 | 'git svn' can track a standard Subversion repository, | |
20 | following the common "trunk/branches/tags" layout, with the --stdlayout option. | |
21 | It can also follow branches and tags in any layout with the -T/-t/-b options | |
22 | (see options to 'init' below, and also the 'clone' command). | |
23 | ||
24 | Once tracking a Subversion repository (with any of the above methods), the Git | |
25 | repository can be updated from Subversion by the 'fetch' command and | |
26 | Subversion updated from Git by the 'dcommit' command. | |
27 | ||
28 | COMMANDS | |
29 | -------- | |
30 | ||
31 | 'init':: | |
32 | Initializes an empty Git repository with additional | |
33 | metadata directories for 'git svn'. The Subversion URL | |
34 | may be specified as a command-line argument, or as full | |
35 | URL arguments to -T/-t/-b. Optionally, the target | |
36 | directory to operate on can be specified as a second | |
37 | argument. Normally this command initializes the current | |
38 | directory. | |
39 | ||
40 | -T<trunk_subdir>;; | |
41 | --trunk=<trunk_subdir>;; | |
42 | -t<tags_subdir>;; | |
43 | --tags=<tags_subdir>;; | |
44 | -b<branches_subdir>;; | |
45 | --branches=<branches_subdir>;; | |
46 | -s;; | |
47 | --stdlayout;; | |
48 | These are optional command-line options for init. Each of | |
49 | these flags can point to a relative repository path | |
50 | (--tags=project/tags) or a full url | |
51 | (--tags=https://foo.org/project/tags). | |
52 | You can specify more than one --tags and/or --branches options, in case | |
53 | your Subversion repository places tags or branches under multiple paths. | |
54 | The option --stdlayout is | |
55 | a shorthand way of setting trunk,tags,branches as the relative paths, | |
56 | which is the Subversion default. If any of the other options are given | |
57 | as well, they take precedence. | |
58 | --no-metadata;; | |
59 | Set the 'noMetadata' option in the [svn-remote] config. | |
60 | This option is not recommended, please read the 'svn.noMetadata' | |
61 | section of this manpage before using this option. | |
62 | --use-svm-props;; | |
63 | Set the 'useSvmProps' option in the [svn-remote] config. | |
64 | --use-svnsync-props;; | |
65 | Set the 'useSvnsyncProps' option in the [svn-remote] config. | |
66 | --rewrite-root=<URL>;; | |
67 | Set the 'rewriteRoot' option in the [svn-remote] config. | |
68 | --rewrite-uuid=<UUID>;; | |
69 | Set the 'rewriteUUID' option in the [svn-remote] config. | |
70 | --username=<user>;; | |
71 | For transports that SVN handles authentication for (http, | |
72 | https, and plain svn), specify the username. For other | |
73 | transports (e.g. `svn+ssh://`), you must include the username in | |
74 | the URL, e.g. `svn+ssh://foo@svn.bar.com/project` | |
75 | --prefix=<prefix>;; | |
76 | This allows one to specify a prefix which is prepended | |
77 | to the names of remotes if trunk/branches/tags are | |
78 | specified. The prefix does not automatically include a | |
79 | trailing slash, so be sure you include one in the | |
80 | argument if that is what you want. If --branches/-b is | |
81 | specified, the prefix must include a trailing slash. | |
82 | Setting a prefix (with a trailing slash) is strongly | |
83 | encouraged in any case, as your SVN-tracking refs will | |
84 | then be located at "refs/remotes/$prefix/*", which is | |
85 | compatible with Git's own remote-tracking ref layout | |
86 | (refs/remotes/$remote/*). Setting a prefix is also useful | |
87 | if you wish to track multiple projects that share a common | |
88 | repository. | |
89 | By default, the prefix is set to 'origin/'. | |
90 | + | |
91 | NOTE: Before Git v2.0, the default prefix was "" (no prefix). This | |
92 | meant that SVN-tracking refs were put at "refs/remotes/*", which is | |
93 | incompatible with how Git's own remote-tracking refs are organized. | |
94 | If you still want the old default, you can get it by passing | |
95 | `--prefix ""` on the command line (`--prefix=""` may not work if | |
96 | your Perl's Getopt::Long is < v2.37). | |
97 | ||
98 | --ignore-refs=<regex>;; | |
99 | When passed to 'init' or 'clone' this regular expression will | |
100 | be preserved as a config key. See 'fetch' for a description | |
101 | of `--ignore-refs`. | |
102 | --ignore-paths=<regex>;; | |
103 | When passed to 'init' or 'clone' this regular expression will | |
104 | be preserved as a config key. See 'fetch' for a description | |
105 | of `--ignore-paths`. | |
106 | --include-paths=<regex>;; | |
107 | When passed to 'init' or 'clone' this regular expression will | |
108 | be preserved as a config key. See 'fetch' for a description | |
109 | of `--include-paths`. | |
110 | --no-minimize-url;; | |
111 | When tracking multiple directories (using --stdlayout, | |
112 | --branches, or --tags options), git svn will attempt to connect | |
113 | to the root (or highest allowed level) of the Subversion | |
114 | repository. This default allows better tracking of history if | |
115 | entire projects are moved within a repository, but may cause | |
116 | issues on repositories where read access restrictions are in | |
117 | place. Passing `--no-minimize-url` will allow git svn to | |
118 | accept URLs as-is without attempting to connect to a higher | |
119 | level directory. This option is off by default when only | |
120 | one URL/branch is tracked (it would do little good). | |
121 | ||
122 | 'fetch':: | |
123 | Fetch unfetched revisions from the Subversion remote we are | |
124 | tracking. The name of the [svn-remote "..."] section in the | |
125 | $GIT_DIR/config file may be specified as an optional | |
126 | command-line argument. | |
127 | + | |
128 | This automatically updates the rev_map if needed (see | |
129 | '$GIT_DIR/svn/\**/.rev_map.*' in the FILES section below for details). | |
130 | ||
131 | --localtime;; | |
132 | Store Git commit times in the local time zone instead of UTC. This | |
133 | makes 'git log' (even without --date=local) show the same times | |
134 | that `svn log` would in the local time zone. | |
135 | + | |
136 | This doesn't interfere with interoperating with the Subversion | |
137 | repository you cloned from, but if you wish for your local Git | |
138 | repository to be able to interoperate with someone else's local Git | |
139 | repository, either don't use this option or you should both use it in | |
140 | the same local time zone. | |
141 | ||
142 | --parent;; | |
143 | Fetch only from the SVN parent of the current HEAD. | |
144 | ||
145 | --ignore-refs=<regex>;; | |
146 | Ignore refs for branches or tags matching the Perl regular | |
147 | expression. A "negative look-ahead assertion" like | |
148 | `^refs/remotes/origin/(?!tags/wanted-tag|wanted-branch).*$` | |
149 | can be used to allow only certain refs. | |
150 | + | |
151 | [verse] | |
152 | config key: svn-remote.<name>.ignore-refs | |
153 | + | |
154 | If the ignore-refs configuration key is set, and the command-line | |
155 | option is also given, both regular expressions will be used. | |
156 | ||
157 | --ignore-paths=<regex>;; | |
158 | This allows one to specify a Perl regular expression that will | |
159 | cause skipping of all matching paths from checkout from SVN. | |
160 | The `--ignore-paths` option should match for every 'fetch' | |
161 | (including automatic fetches due to 'clone', 'dcommit', | |
162 | 'rebase', etc) on a given repository. | |
163 | + | |
164 | [verse] | |
165 | config key: svn-remote.<name>.ignore-paths | |
166 | + | |
167 | If the ignore-paths configuration key is set, and the command-line | |
168 | option is also given, both regular expressions will be used. | |
169 | + | |
170 | Examples: | |
171 | + | |
172 | -- | |
173 | Skip "doc*" directory for every fetch;; | |
174 | + | |
175 | ------------------------------------------------------------------------ | |
176 | --ignore-paths="^doc" | |
177 | ------------------------------------------------------------------------ | |
178 | ||
179 | Skip "branches" and "tags" of first level directories;; | |
180 | + | |
181 | ------------------------------------------------------------------------ | |
182 | --ignore-paths="^[^/]+/(?:branches|tags)" | |
183 | ------------------------------------------------------------------------ | |
184 | -- | |
185 | ||
186 | --include-paths=<regex>;; | |
187 | This allows one to specify a Perl regular expression that will | |
188 | cause the inclusion of only matching paths from checkout from SVN. | |
189 | The `--include-paths` option should match for every 'fetch' | |
190 | (including automatic fetches due to 'clone', 'dcommit', | |
191 | 'rebase', etc) on a given repository. `--ignore-paths` takes | |
192 | precedence over `--include-paths`. | |
193 | + | |
194 | [verse] | |
195 | config key: svn-remote.<name>.include-paths | |
196 | ||
197 | --log-window-size=<n>;; | |
198 | Fetch <n> log entries per request when scanning Subversion history. | |
199 | The default is 100. For very large Subversion repositories, larger | |
200 | values may be needed for 'clone'/'fetch' to complete in reasonable | |
201 | time. But overly large values may lead to higher memory usage and | |
202 | request timeouts. | |
203 | ||
204 | 'clone':: | |
205 | Runs 'init' and 'fetch'. It will automatically create a | |
206 | directory based on the basename of the URL passed to it; | |
207 | or if a second argument is passed; it will create a directory | |
208 | and work within that. It accepts all arguments that the | |
209 | 'init' and 'fetch' commands accept; with the exception of | |
210 | `--fetch-all` and `--parent`. After a repository is cloned, | |
211 | the 'fetch' command will be able to update revisions without | |
212 | affecting the working tree; and the 'rebase' command will be | |
213 | able to update the working tree with the latest changes. | |
214 | ||
215 | --preserve-empty-dirs;; | |
216 | Create a placeholder file in the local Git repository for each | |
217 | empty directory fetched from Subversion. This includes directories | |
218 | that become empty by removing all entries in the Subversion | |
219 | repository (but not the directory itself). The placeholder files | |
220 | are also tracked and removed when no longer necessary. | |
221 | ||
222 | --placeholder-filename=<filename>;; | |
223 | Set the name of placeholder files created by --preserve-empty-dirs. | |
224 | Default: ".gitignore" | |
225 | ||
226 | 'rebase':: | |
227 | This fetches revisions from the SVN parent of the current HEAD | |
228 | and rebases the current (uncommitted to SVN) work against it. | |
229 | + | |
230 | This works similarly to `svn update` or 'git pull' except that | |
231 | it preserves linear history with 'git rebase' instead of | |
232 | 'git merge' for ease of dcommitting with 'git svn'. | |
233 | + | |
234 | This accepts all options that 'git svn fetch' and 'git rebase' | |
235 | accept. However, `--fetch-all` only fetches from the current | |
236 | [svn-remote], and not all [svn-remote] definitions. | |
237 | + | |
238 | Like 'git rebase'; this requires that the working tree be clean | |
239 | and have no uncommitted changes. | |
240 | + | |
241 | This automatically updates the rev_map if needed (see | |
242 | '$GIT_DIR/svn/\**/.rev_map.*' in the FILES section below for details). | |
243 | ||
244 | -l;; | |
245 | --local;; | |
246 | Do not fetch remotely; only run 'git rebase' against the | |
247 | last fetched commit from the upstream SVN. | |
248 | ||
249 | 'dcommit':: | |
250 | Commit each diff from the current branch directly to the SVN | |
251 | repository, and then rebase or reset (depending on whether or | |
252 | not there is a diff between SVN and head). This will create | |
253 | a revision in SVN for each commit in Git. | |
254 | + | |
255 | When an optional Git branch name (or a Git commit object name) | |
256 | is specified as an argument, the subcommand works on the specified | |
257 | branch, not on the current branch. | |
258 | + | |
259 | Use of 'dcommit' is preferred to 'set-tree' (below). | |
260 | + | |
261 | --no-rebase;; | |
262 | After committing, do not rebase or reset. | |
263 | --commit-url <URL>;; | |
264 | Commit to this SVN URL (the full path). This is intended to | |
265 | allow existing 'git svn' repositories created with one transport | |
266 | method (e.g. `svn://` or `http://` for anonymous read) to be | |
267 | reused if a user is later given access to an alternate transport | |
268 | method (e.g. `svn+ssh://` or `https://`) for commit. | |
269 | + | |
270 | [verse] | |
271 | config key: svn-remote.<name>.commiturl | |
272 | config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options) | |
273 | + | |
274 | Note that the SVN URL of the commiturl config key includes the SVN branch. | |
275 | If you rather want to set the commit URL for an entire SVN repository use | |
276 | svn-remote.<name>.pushurl instead. | |
277 | + | |
278 | Using this option for any other purpose (don't ask) is very strongly | |
279 | discouraged. | |
280 | ||
281 | --mergeinfo=<mergeinfo>;; | |
282 | Add the given merge information during the dcommit | |
283 | (e.g. `--mergeinfo="/branches/foo:1-10"`). All svn server versions can | |
284 | store this information (as a property), and svn clients starting from | |
285 | version 1.5 can make use of it. To specify merge information from multiple | |
286 | branches, use a single space character between the branches | |
287 | (`--mergeinfo="/branches/foo:1-10 /branches/bar:3,5-6,8"`) | |
288 | + | |
289 | [verse] | |
290 | config key: svn.pushmergeinfo | |
291 | + | |
292 | This option will cause git-svn to attempt to automatically populate the | |
293 | svn:mergeinfo property in the SVN repository when possible. Currently, this can | |
294 | only be done when dcommitting non-fast-forward merges where all parents but the | |
295 | first have already been pushed into SVN. | |
296 | ||
297 | --interactive;; | |
298 | Ask the user to confirm that a patch set should actually be sent to SVN. | |
299 | For each patch, one may answer "yes" (accept this patch), "no" (discard this | |
300 | patch), "all" (accept all patches), or "quit". | |
301 | + | |
302 | 'git svn dcommit' returns immediately if answer is "no" or "quit", without | |
303 | committing anything to SVN. | |
304 | ||
305 | 'branch':: | |
306 | Create a branch in the SVN repository. | |
307 | ||
308 | -m;; | |
309 | --message;; | |
310 | Allows to specify the commit message. | |
311 | ||
312 | -t;; | |
313 | --tag;; | |
314 | Create a tag by using the tags_subdir instead of the branches_subdir | |
315 | specified during git svn init. | |
316 | ||
317 | -d<path>;; | |
318 | --destination=<path>;; | |
319 | ||
320 | If more than one --branches (or --tags) option was given to the 'init' | |
321 | or 'clone' command, you must provide the location of the branch (or | |
322 | tag) you wish to create in the SVN repository. <path> specifies which | |
323 | path to use to create the branch or tag and should match the pattern | |
324 | on the left-hand side of one of the configured branches or tags | |
325 | refspecs. You can see these refspecs with the commands | |
326 | + | |
327 | git config --get-all svn-remote.<name>.branches | |
328 | git config --get-all svn-remote.<name>.tags | |
329 | + | |
330 | where <name> is the name of the SVN repository as specified by the -R option to | |
331 | 'init' (or "svn" by default). | |
332 | ||
333 | --username;; | |
334 | Specify the SVN username to perform the commit as. This option overrides | |
335 | the 'username' configuration property. | |
336 | ||
337 | --commit-url;; | |
338 | Use the specified URL to connect to the destination Subversion | |
339 | repository. This is useful in cases where the source SVN | |
340 | repository is read-only. This option overrides configuration | |
341 | property 'commiturl'. | |
342 | + | |
343 | git config --get-all svn-remote.<name>.commiturl | |
344 | + | |
345 | ||
346 | --parents;; | |
347 | Create parent folders. This parameter is equivalent to the parameter | |
348 | --parents on svn cp commands and is useful for non-standard repository | |
349 | layouts. | |
350 | ||
351 | 'tag':: | |
352 | Create a tag in the SVN repository. This is a shorthand for | |
353 | 'branch -t'. | |
354 | ||
355 | 'log':: | |
356 | This should make it easy to look up svn log messages when svn | |
357 | users refer to -r/--revision numbers. | |
358 | + | |
359 | The following features from `svn log' are supported: | |
360 | + | |
361 | -- | |
362 | -r <n>[:<n>];; | |
363 | --revision=<n>[:<n>];; | |
364 | is supported, non-numeric args are not: | |
365 | HEAD, NEXT, BASE, PREV, etc ... | |
366 | -v;; | |
367 | --verbose;; | |
368 | it's not completely compatible with the --verbose | |
369 | output in svn log, but reasonably close. | |
370 | --limit=<n>;; | |
371 | is NOT the same as --max-count, doesn't count | |
372 | merged/excluded commits | |
373 | --incremental;; | |
374 | supported | |
375 | -- | |
376 | + | |
377 | New features: | |
378 | + | |
379 | -- | |
380 | --show-commit;; | |
381 | shows the Git commit sha1, as well | |
382 | --oneline;; | |
383 | our version of --pretty=oneline | |
384 | -- | |
385 | + | |
386 | NOTE: SVN itself only stores times in UTC and nothing else. The regular svn | |
387 | client converts the UTC time to the local time (or based on the TZ= | |
388 | environment). This command has the same behaviour. | |
389 | + | |
390 | Any other arguments are passed directly to 'git log' | |
391 | ||
392 | 'blame':: | |
393 | Show what revision and author last modified each line of a file. The | |
394 | output of this mode is format-compatible with the output of | |
395 | `svn blame' by default. Like the SVN blame command, | |
396 | local uncommitted changes in the working tree are ignored; | |
397 | the version of the file in the HEAD revision is annotated. Unknown | |
398 | arguments are passed directly to 'git blame'. | |
399 | + | |
400 | --git-format;; | |
401 | Produce output in the same format as 'git blame', but with | |
402 | SVN revision numbers instead of Git commit hashes. In this mode, | |
403 | changes that haven't been committed to SVN (including local | |
404 | working-copy edits) are shown as revision 0. | |
405 | ||
406 | 'find-rev':: | |
407 | When given an SVN revision number of the form 'rN', returns the | |
408 | corresponding Git commit hash (this can optionally be followed by a | |
409 | tree-ish to specify which branch should be searched). When given a | |
410 | tree-ish, returns the corresponding SVN revision number. | |
411 | + | |
412 | -B;; | |
413 | --before;; | |
414 | Don't require an exact match if given an SVN revision, instead find | |
415 | the commit corresponding to the state of the SVN repository (on the | |
416 | current branch) at the specified revision. | |
417 | + | |
418 | -A;; | |
419 | --after;; | |
420 | Don't require an exact match if given an SVN revision; if there is | |
421 | not an exact match return the closest match searching forward in the | |
422 | history. | |
423 | ||
424 | 'set-tree':: | |
425 | You should consider using 'dcommit' instead of this command. | |
426 | Commit specified commit or tree objects to SVN. This relies on | |
427 | your imported fetch data being up to date. This makes | |
428 | absolutely no attempts to do patching when committing to SVN, it | |
429 | simply overwrites files with those specified in the tree or | |
430 | commit. All merging is assumed to have taken place | |
431 | independently of 'git svn' functions. | |
432 | ||
433 | 'create-ignore':: | |
434 | Recursively finds the svn:ignore property on directories and | |
435 | creates matching .gitignore files. The resulting files are staged to | |
436 | be committed, but are not committed. Use -r/--revision to refer to a | |
437 | specific revision. | |
438 | ||
439 | 'show-ignore':: | |
440 | Recursively finds and lists the svn:ignore property on | |
441 | directories. The output is suitable for appending to | |
442 | the $GIT_DIR/info/exclude file. | |
443 | ||
444 | 'mkdirs':: | |
445 | Attempts to recreate empty directories that core Git cannot track | |
446 | based on information in $GIT_DIR/svn/<refname>/unhandled.log files. | |
447 | Empty directories are automatically recreated when using | |
448 | "git svn clone" and "git svn rebase", so "mkdirs" is intended | |
449 | for use after commands like "git checkout" or "git reset". | |
450 | (See the svn-remote.<name>.automkdirs config file option for | |
451 | more information.) | |
452 | ||
453 | 'commit-diff':: | |
454 | Commits the diff of two tree-ish arguments from the | |
455 | command-line. This command does not rely on being inside a `git svn | |
456 | init`-ed repository. This command takes three arguments, (a) the | |
457 | original tree to diff against, (b) the new tree result, (c) the | |
458 | URL of the target Subversion repository. The final argument | |
459 | (URL) may be omitted if you are working from a 'git svn'-aware | |
460 | repository (that has been `init`-ed with 'git svn'). | |
461 | The -r<revision> option is required for this. | |
462 | + | |
463 | The commit message is supplied either directly with the `-m` or `-F` | |
464 | option, or indirectly from the tag or commit when the second tree-ish | |
465 | denotes such an object, or it is requested by invoking an editor (see | |
466 | `--edit` option below). | |
467 | ||
468 | -m <msg>;; | |
469 | --message=<msg>;; | |
470 | Use the given `msg` as the commit message. This option | |
471 | disables the `--edit` option. | |
472 | ||
473 | -F <filename>;; | |
474 | --file=<filename>;; | |
475 | Take the commit message from the given file. This option | |
476 | disables the `--edit` option. | |
477 | ||
478 | 'info':: | |
479 | Shows information about a file or directory similar to what | |
480 | `svn info' provides. Does not currently support a -r/--revision | |
481 | argument. Use the --url option to output only the value of the | |
482 | 'URL:' field. | |
483 | ||
484 | 'proplist':: | |
485 | Lists the properties stored in the Subversion repository about a | |
486 | given file or directory. Use -r/--revision to refer to a specific | |
487 | Subversion revision. | |
488 | ||
489 | 'propget':: | |
490 | Gets the Subversion property given as the first argument, for a | |
491 | file. A specific revision can be specified with -r/--revision. | |
492 | ||
493 | 'propset':: | |
494 | Sets the Subversion property given as the first argument, to the | |
495 | value given as the second argument for the file given as the | |
496 | third argument. | |
497 | + | |
498 | Example: | |
499 | + | |
500 | ------------------------------------------------------------------------ | |
501 | git svn propset svn:keywords "FreeBSD=%H" devel/py-tipper/Makefile | |
502 | ------------------------------------------------------------------------ | |
503 | + | |
504 | This will set the property 'svn:keywords' to 'FreeBSD=%H' for the file | |
505 | 'devel/py-tipper/Makefile'. | |
506 | ||
507 | 'show-externals':: | |
508 | Shows the Subversion externals. Use -r/--revision to specify a | |
509 | specific revision. | |
510 | ||
511 | 'gc':: | |
512 | Compress $GIT_DIR/svn/<refname>/unhandled.log files and remove | |
513 | $GIT_DIR/svn/<refname>/index files. | |
514 | ||
515 | 'reset':: | |
516 | Undoes the effects of 'fetch' back to the specified revision. | |
517 | This allows you to re-'fetch' an SVN revision. Normally the | |
518 | contents of an SVN revision should never change and 'reset' | |
519 | should not be necessary. However, if SVN permissions change, | |
520 | or if you alter your --ignore-paths option, a 'fetch' may fail | |
521 | with "not found in commit" (file not previously visible) or | |
522 | "checksum mismatch" (missed a modification). If the problem | |
523 | file cannot be ignored forever (with --ignore-paths) the only | |
524 | way to repair the repo is to use 'reset'. | |
525 | + | |
526 | Only the rev_map and refs/remotes/git-svn are changed (see | |
527 | '$GIT_DIR/svn/\**/.rev_map.*' in the FILES section below for details). | |
528 | Follow 'reset' with a 'fetch' and then 'git reset' or 'git rebase' to | |
529 | move local branches onto the new tree. | |
530 | ||
531 | -r <n>;; | |
532 | --revision=<n>;; | |
533 | Specify the most recent revision to keep. All later revisions | |
534 | are discarded. | |
535 | -p;; | |
536 | --parent;; | |
537 | Discard the specified revision as well, keeping the nearest | |
538 | parent instead. | |
539 | Example:;; | |
540 | Assume you have local changes in "master", but you need to refetch "r2". | |
541 | + | |
542 | ------------ | |
543 | r1---r2---r3 remotes/git-svn | |
544 | \ | |
545 | A---B master | |
546 | ------------ | |
547 | + | |
548 | Fix the ignore-paths or SVN permissions problem that caused "r2" to | |
549 | be incomplete in the first place. Then: | |
550 | + | |
551 | [verse] | |
552 | git svn reset -r2 -p | |
553 | git svn fetch | |
554 | + | |
555 | ------------ | |
556 | r1---r2'--r3' remotes/git-svn | |
557 | \ | |
558 | r2---r3---A---B master | |
559 | ------------ | |
560 | + | |
561 | Then fixup "master" with 'git rebase'. | |
562 | Do NOT use 'git merge' or your history will not be compatible with a | |
563 | future 'dcommit'! | |
564 | + | |
565 | [verse] | |
566 | git rebase --onto remotes/git-svn A^ master | |
567 | + | |
568 | ------------ | |
569 | r1---r2'--r3' remotes/git-svn | |
570 | \ | |
571 | A'--B' master | |
572 | ------------ | |
573 | ||
574 | OPTIONS | |
575 | ------- | |
576 | ||
577 | --shared[=(false|true|umask|group|all|world|everybody)]:: | |
578 | --template=<template_directory>:: | |
579 | Only used with the 'init' command. | |
580 | These are passed directly to 'git init'. | |
581 | ||
582 | -r <arg>:: | |
583 | --revision <arg>:: | |
584 | Used with the 'fetch' command. | |
585 | + | |
586 | This allows revision ranges for partial/cauterized history | |
587 | to be supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges), | |
588 | $NUMBER:HEAD, and BASE:$NUMBER are all supported. | |
589 | + | |
590 | This can allow you to make partial mirrors when running fetch; | |
591 | but is generally not recommended because history will be skipped | |
592 | and lost. | |
593 | ||
594 | -:: | |
595 | --stdin:: | |
596 | Only used with the 'set-tree' command. | |
597 | + | |
598 | Read a list of commits from stdin and commit them in reverse | |
599 | order. Only the leading sha1 is read from each line, so | |
600 | 'git rev-list --pretty=oneline' output can be used. | |
601 | ||
602 | --rmdir:: | |
603 | Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. | |
604 | + | |
605 | Remove directories from the SVN tree if there are no files left | |
606 | behind. SVN can version empty directories, and they are not | |
607 | removed by default if there are no files left in them. Git | |
608 | cannot version empty directories. Enabling this flag will make | |
609 | the commit to SVN act like Git. | |
610 | + | |
611 | [verse] | |
612 | config key: svn.rmdir | |
613 | ||
614 | -e:: | |
615 | --edit:: | |
616 | Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. | |
617 | + | |
618 | Edit the commit message before committing to SVN. This is off by | |
619 | default for objects that are commits, and forced on when committing | |
620 | tree objects. | |
621 | + | |
622 | [verse] | |
623 | config key: svn.edit | |
624 | ||
625 | -l<num>:: | |
626 | --find-copies-harder:: | |
627 | Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. | |
628 | + | |
629 | They are both passed directly to 'git diff-tree'; see | |
630 | linkgit:git-diff-tree[1] for more information. | |
631 | + | |
632 | [verse] | |
633 | config key: svn.l | |
634 | config key: svn.findcopiesharder | |
635 | ||
636 | -A<filename>:: | |
637 | --authors-file=<filename>:: | |
638 | Syntax is compatible with the file used by 'git cvsimport' but | |
639 | an empty email address can be supplied with '<>': | |
640 | + | |
641 | ------------------------------------------------------------------------ | |
642 | loginname = Joe User <user@example.com> | |
643 | ------------------------------------------------------------------------ | |
644 | + | |
645 | If this option is specified and 'git svn' encounters an SVN | |
646 | committer name that does not exist in the authors-file, 'git svn' | |
647 | will abort operation. The user will then have to add the | |
648 | appropriate entry. Re-running the previous 'git svn' command | |
649 | after the authors-file is modified should continue operation. | |
650 | + | |
651 | [verse] | |
652 | config key: svn.authorsfile | |
653 | ||
654 | --authors-prog=<filename>:: | |
655 | If this option is specified, for each SVN committer name that | |
656 | does not exist in the authors file, the given file is executed | |
657 | with the committer name as the first argument. The program is | |
658 | expected to return a single line of the form "Name <email>" or | |
659 | "Name <>", which will be treated as if included in the authors | |
660 | file. | |
661 | + | |
662 | Due to historical reasons a relative 'filename' is first searched | |
663 | relative to the current directory for 'init' and 'clone' and relative | |
664 | to the root of the working tree for 'fetch'. If 'filename' is | |
665 | not found, it is searched like any other command in '$PATH'. | |
666 | + | |
667 | [verse] | |
668 | config key: svn.authorsProg | |
669 | ||
670 | -q:: | |
671 | --quiet:: | |
672 | Make 'git svn' less verbose. Specify a second time to make it | |
673 | even less verbose. | |
674 | ||
675 | -m:: | |
676 | --merge:: | |
677 | -s<strategy>:: | |
678 | --strategy=<strategy>:: | |
679 | -p:: | |
680 | --preserve-merges:: | |
681 | These are only used with the 'dcommit' and 'rebase' commands. | |
682 | + | |
683 | Passed directly to 'git rebase' when using 'dcommit' if a | |
684 | 'git reset' cannot be used (see 'dcommit'). | |
685 | ||
686 | -n:: | |
687 | --dry-run:: | |
688 | This can be used with the 'dcommit', 'rebase', 'branch' and | |
689 | 'tag' commands. | |
690 | + | |
691 | For 'dcommit', print out the series of Git arguments that would show | |
692 | which diffs would be committed to SVN. | |
693 | + | |
694 | For 'rebase', display the local branch associated with the upstream svn | |
695 | repository associated with the current branch and the URL of svn | |
696 | repository that will be fetched from. | |
697 | + | |
698 | For 'branch' and 'tag', display the urls that will be used for copying when | |
699 | creating the branch or tag. | |
700 | ||
701 | --use-log-author:: | |
702 | When retrieving svn commits into Git (as part of 'fetch', 'rebase', or | |
703 | 'dcommit' operations), look for the first `From:` or `Signed-off-by:` line | |
704 | in the log message and use that as the author string. | |
705 | + | |
706 | [verse] | |
707 | config key: svn.useLogAuthor | |
708 | ||
709 | --add-author-from:: | |
710 | When committing to svn from Git (as part of 'set-tree' or 'dcommit' | |
711 | operations), if the existing log message doesn't already have a | |
712 | `From:` or `Signed-off-by:` line, append a `From:` line based on the | |
713 | Git commit's author string. If you use this, then `--use-log-author` | |
714 | will retrieve a valid author string for all commits. | |
715 | + | |
716 | [verse] | |
717 | config key: svn.addAuthorFrom | |
718 | ||
719 | ADVANCED OPTIONS | |
720 | ---------------- | |
721 | ||
722 | -i<GIT_SVN_ID>:: | |
723 | --id <GIT_SVN_ID>:: | |
724 | This sets GIT_SVN_ID (instead of using the environment). This | |
725 | allows the user to override the default refname to fetch from | |
726 | when tracking a single URL. The 'log' and 'dcommit' commands | |
727 | no longer require this switch as an argument. | |
728 | ||
729 | -R<remote name>:: | |
730 | --svn-remote <remote name>:: | |
731 | Specify the [svn-remote "<remote name>"] section to use, | |
732 | this allows SVN multiple repositories to be tracked. | |
733 | Default: "svn" | |
734 | ||
735 | --follow-parent:: | |
736 | This option is only relevant if we are tracking branches (using | |
737 | one of the repository layout options --trunk, --tags, | |
738 | --branches, --stdlayout). For each tracked branch, try to find | |
739 | out where its revision was copied from, and set | |
740 | a suitable parent in the first Git commit for the branch. | |
741 | This is especially helpful when we're tracking a directory | |
742 | that has been moved around within the repository. If this | |
743 | feature is disabled, the branches created by 'git svn' will all | |
744 | be linear and not share any history, meaning that there will be | |
745 | no information on where branches were branched off or merged. | |
746 | However, following long/convoluted histories can take a long | |
747 | time, so disabling this feature may speed up the cloning | |
748 | process. This feature is enabled by default, use | |
749 | --no-follow-parent to disable it. | |
750 | + | |
751 | [verse] | |
752 | config key: svn.followparent | |
753 | ||
754 | CONFIG FILE-ONLY OPTIONS | |
755 | ------------------------ | |
756 | ||
757 | svn.noMetadata:: | |
758 | svn-remote.<name>.noMetadata:: | |
759 | This gets rid of the 'git-svn-id:' lines at the end of every commit. | |
760 | + | |
761 | This option can only be used for one-shot imports as 'git svn' | |
762 | will not be able to fetch again without metadata. Additionally, | |
763 | if you lose your '$GIT_DIR/svn/\**/.rev_map.*' files, 'git svn' will not | |
764 | be able to rebuild them. | |
765 | + | |
766 | The 'git svn log' command will not work on repositories using | |
767 | this, either. Using this conflicts with the 'useSvmProps' | |
768 | option for (hopefully) obvious reasons. | |
769 | + | |
770 | This option is NOT recommended as it makes it difficult to track down | |
771 | old references to SVN revision numbers in existing documentation, bug | |
772 | reports, and archives. If you plan to eventually migrate from SVN to | |
773 | Git and are certain about dropping SVN history, consider | |
774 | https://github.com/newren/git-filter-repo[git-filter-repo] instead. | |
775 | filter-repo also allows reformatting of metadata for ease-of-reading | |
776 | and rewriting authorship info for non-"svn.authorsFile" users. | |
777 | ||
778 | svn.useSvmProps:: | |
779 | svn-remote.<name>.useSvmProps:: | |
780 | This allows 'git svn' to re-map repository URLs and UUIDs from | |
781 | mirrors created using SVN::Mirror (or svk) for metadata. | |
782 | + | |
783 | If an SVN revision has a property, "svm:headrev", it is likely | |
784 | that the revision was created by SVN::Mirror (also used by SVK). | |
785 | The property contains a repository UUID and a revision. We want | |
786 | to make it look like we are mirroring the original URL, so | |
787 | introduce a helper function that returns the original identity | |
788 | URL and UUID, and use it when generating metadata in commit | |
789 | messages. | |
790 | ||
791 | svn.useSvnsyncProps:: | |
792 | svn-remote.<name>.useSvnsyncprops:: | |
793 | Similar to the useSvmProps option; this is for users | |
794 | of the svnsync(1) command distributed with SVN 1.4.x and | |
795 | later. | |
796 | ||
797 | svn-remote.<name>.rewriteRoot:: | |
798 | This allows users to create repositories from alternate | |
799 | URLs. For example, an administrator could run 'git svn' on the | |
800 | server locally (accessing via file://) but wish to distribute | |
801 | the repository with a public http:// or svn:// URL in the | |
802 | metadata so users of it will see the public URL. | |
803 | ||
804 | svn-remote.<name>.rewriteUUID:: | |
805 | Similar to the useSvmProps option; this is for users who need | |
806 | to remap the UUID manually. This may be useful in situations | |
807 | where the original UUID is not available via either useSvmProps | |
808 | or useSvnsyncProps. | |
809 | ||
810 | svn-remote.<name>.pushurl:: | |
811 | ||
812 | Similar to Git's `remote.<name>.pushurl`, this key is designed | |
813 | to be used in cases where 'url' points to an SVN repository | |
814 | via a read-only transport, to provide an alternate read/write | |
815 | transport. It is assumed that both keys point to the same | |
816 | repository. Unlike 'commiturl', 'pushurl' is a base path. If | |
817 | either 'commiturl' or 'pushurl' could be used, 'commiturl' | |
818 | takes precedence. | |
819 | ||
820 | svn.brokenSymlinkWorkaround:: | |
821 | This disables potentially expensive checks to workaround | |
822 | broken symlinks checked into SVN by broken clients. Set this | |
823 | option to "false" if you track a SVN repository with many | |
824 | empty blobs that are not symlinks. This option may be changed | |
825 | while 'git svn' is running and take effect on the next | |
826 | revision fetched. If unset, 'git svn' assumes this option to | |
827 | be "true". | |
828 | ||
829 | svn.pathnameencoding:: | |
830 | This instructs git svn to recode pathnames to a given encoding. | |
831 | It can be used by windows users and by those who work in non-utf8 | |
832 | locales to avoid corrupted file names with non-ASCII characters. | |
833 | Valid encodings are the ones supported by Perl's Encode module. | |
834 | ||
835 | svn-remote.<name>.automkdirs:: | |
836 | Normally, the "git svn clone" and "git svn rebase" commands | |
837 | attempt to recreate empty directories that are in the | |
838 | Subversion repository. If this option is set to "false", then | |
839 | empty directories will only be created if the "git svn mkdirs" | |
840 | command is run explicitly. If unset, 'git svn' assumes this | |
841 | option to be "true". | |
842 | ||
843 | Since the noMetadata, rewriteRoot, rewriteUUID, useSvnsyncProps and useSvmProps | |
844 | options all affect the metadata generated and used by 'git svn'; they | |
845 | *must* be set in the configuration file before any history is imported | |
846 | and these settings should never be changed once they are set. | |
847 | ||
848 | Additionally, only one of these options can be used per svn-remote | |
849 | section because they affect the 'git-svn-id:' metadata line, except | |
850 | for rewriteRoot and rewriteUUID which can be used together. | |
851 | ||
852 | ||
853 | BASIC EXAMPLES | |
854 | -------------- | |
855 | ||
856 | Tracking and contributing to the trunk of a Subversion-managed project | |
857 | (ignoring tags and branches): | |
858 | ||
859 | ------------------------------------------------------------------------ | |
860 | # Clone a repo (like git clone): | |
861 | git svn clone http://svn.example.com/project/trunk | |
862 | # Enter the newly cloned directory: | |
863 | cd trunk | |
864 | # You should be on master branch, double-check with 'git branch' | |
865 | git branch | |
866 | # Do some work and commit locally to Git: | |
867 | git commit ... | |
868 | # Something is committed to SVN, rebase your local changes against the | |
869 | # latest changes in SVN: | |
870 | git svn rebase | |
871 | # Now commit your changes (that were committed previously using Git) to SVN, | |
872 | # as well as automatically updating your working HEAD: | |
873 | git svn dcommit | |
874 | # Append svn:ignore settings to the default Git exclude file: | |
875 | git svn show-ignore >> .git/info/exclude | |
876 | ------------------------------------------------------------------------ | |
877 | ||
878 | Tracking and contributing to an entire Subversion-managed project | |
879 | (complete with a trunk, tags and branches): | |
880 | ||
881 | ------------------------------------------------------------------------ | |
882 | # Clone a repo with standard SVN directory layout (like git clone): | |
883 | git svn clone http://svn.example.com/project --stdlayout --prefix svn/ | |
884 | # Or, if the repo uses a non-standard directory layout: | |
885 | git svn clone http://svn.example.com/project -T tr -b branch -t tag --prefix svn/ | |
886 | # View all branches and tags you have cloned: | |
887 | git branch -r | |
888 | # Create a new branch in SVN | |
889 | git svn branch waldo | |
890 | # Reset your master to trunk (or any other branch, replacing 'trunk' | |
891 | # with the appropriate name): | |
892 | git reset --hard svn/trunk | |
893 | # You may only dcommit to one branch/tag/trunk at a time. The usage | |
894 | # of dcommit/rebase/show-ignore should be the same as above. | |
895 | ------------------------------------------------------------------------ | |
896 | ||
897 | The initial 'git svn clone' can be quite time-consuming | |
898 | (especially for large Subversion repositories). If multiple | |
899 | people (or one person with multiple machines) want to use | |
900 | 'git svn' to interact with the same Subversion repository, you can | |
901 | do the initial 'git svn clone' to a repository on a server and | |
902 | have each person clone that repository with 'git clone': | |
903 | ||
904 | ------------------------------------------------------------------------ | |
905 | # Do the initial import on a server | |
906 | ssh server "cd /pub && git svn clone http://svn.example.com/project [options...]" | |
907 | # Clone locally - make sure the refs/remotes/ space matches the server | |
908 | mkdir project | |
909 | cd project | |
910 | git init | |
911 | git remote add origin server:/pub/project | |
912 | git config --replace-all remote.origin.fetch '+refs/remotes/*:refs/remotes/*' | |
913 | git fetch | |
914 | # Prevent fetch/pull from remote Git server in the future, | |
915 | # we only want to use git svn for future updates | |
916 | git config --remove-section remote.origin | |
917 | # Create a local branch from one of the branches just fetched | |
918 | git checkout -b master FETCH_HEAD | |
919 | # Initialize 'git svn' locally (be sure to use the same URL and | |
920 | # --stdlayout/-T/-b/-t/--prefix options as were used on server) | |
921 | git svn init http://svn.example.com/project [options...] | |
922 | # Pull the latest changes from Subversion | |
923 | git svn rebase | |
924 | ------------------------------------------------------------------------ | |
925 | ||
926 | REBASE VS. PULL/MERGE | |
927 | --------------------- | |
928 | Prefer to use 'git svn rebase' or 'git rebase', rather than | |
929 | 'git pull' or 'git merge' to synchronize unintegrated commits with a 'git svn' | |
930 | branch. Doing so will keep the history of unintegrated commits linear with | |
931 | respect to the upstream SVN repository and allow the use of the preferred | |
932 | 'git svn dcommit' subcommand to push unintegrated commits back into SVN. | |
933 | ||
934 | Originally, 'git svn' recommended that developers pulled or merged from | |
935 | the 'git svn' branch. This was because the author favored | |
936 | `git svn set-tree B` to commit a single head rather than the | |
937 | `git svn set-tree A..B` notation to commit multiple commits. Use of | |
938 | 'git pull' or 'git merge' with `git svn set-tree A..B` will cause non-linear | |
939 | history to be flattened when committing into SVN and this can lead to merge | |
940 | commits unexpectedly reversing previous commits in SVN. | |
941 | ||
942 | MERGE TRACKING | |
943 | -------------- | |
944 | While 'git svn' can track | |
945 | copy history (including branches and tags) for repositories adopting a | |
946 | standard layout, it cannot yet represent merge history that happened | |
947 | inside git back upstream to SVN users. Therefore it is advised that | |
948 | users keep history as linear as possible inside Git to ease | |
949 | compatibility with SVN (see the CAVEATS section below). | |
950 | ||
951 | HANDLING OF SVN BRANCHES | |
952 | ------------------------ | |
953 | If 'git svn' is configured to fetch branches (and --follow-branches | |
954 | is in effect), it sometimes creates multiple Git branches for one | |
955 | SVN branch, where the additional branches have names of the form | |
956 | 'branchname@nnn' (with nnn an SVN revision number). These additional | |
957 | branches are created if 'git svn' cannot find a parent commit for the | |
958 | first commit in an SVN branch, to connect the branch to the history of | |
959 | the other branches. | |
960 | ||
961 | Normally, the first commit in an SVN branch consists | |
962 | of a copy operation. 'git svn' will read this commit to get the SVN | |
963 | revision the branch was created from. It will then try to find the | |
964 | Git commit that corresponds to this SVN revision, and use that as the | |
965 | parent of the branch. However, it is possible that there is no suitable | |
966 | Git commit to serve as parent. This will happen, among other reasons, | |
967 | if the SVN branch is a copy of a revision that was not fetched by 'git | |
968 | svn' (e.g. because it is an old revision that was skipped with | |
969 | `--revision`), or if in SVN a directory was copied that is not tracked | |
970 | by 'git svn' (such as a branch that is not tracked at all, or a | |
971 | subdirectory of a tracked branch). In these cases, 'git svn' will still | |
972 | create a Git branch, but instead of using an existing Git commit as the | |
973 | parent of the branch, it will read the SVN history of the directory the | |
974 | branch was copied from and create appropriate Git commits. This is | |
975 | indicated by the message "Initializing parent: <branchname>". | |
976 | ||
977 | Additionally, it will create a special branch named | |
978 | '<branchname>@<SVN-Revision>', where <SVN-Revision> is the SVN revision | |
979 | number the branch was copied from. This branch will point to the newly | |
980 | created parent commit of the branch. If in SVN the branch was deleted | |
981 | and later recreated from a different version, there will be multiple | |
982 | such branches with an '@'. | |
983 | ||
984 | Note that this may mean that multiple Git commits are created for a | |
985 | single SVN revision. | |
986 | ||
987 | An example: in an SVN repository with a standard | |
988 | trunk/tags/branches layout, a directory trunk/sub is created in r.100. | |
989 | In r.200, trunk/sub is branched by copying it to branches/. 'git svn | |
990 | clone -s' will then create a branch 'sub'. It will also create new Git | |
991 | commits for r.100 through r.199 and use these as the history of branch | |
992 | 'sub'. Thus there will be two Git commits for each revision from r.100 | |
993 | to r.199 (one containing trunk/, one containing trunk/sub/). Finally, | |
994 | it will create a branch 'sub@200' pointing to the new parent commit of | |
995 | branch 'sub' (i.e. the commit for r.200 and trunk/sub/). | |
996 | ||
997 | CAVEATS | |
998 | ------- | |
999 | ||
1000 | For the sake of simplicity and interoperating with Subversion, | |
1001 | it is recommended that all 'git svn' users clone, fetch and dcommit | |
1002 | directly from the SVN server, and avoid all 'git clone'/'pull'/'merge'/'push' | |
1003 | operations between Git repositories and branches. The recommended | |
1004 | method of exchanging code between Git branches and users is | |
1005 | 'git format-patch' and 'git am', or just 'dcommit'ing to the SVN repository. | |
1006 | ||
1007 | Running 'git merge' or 'git pull' is NOT recommended on a branch you | |
1008 | plan to 'dcommit' from because Subversion users cannot see any | |
1009 | merges you've made. Furthermore, if you merge or pull from a Git branch | |
1010 | that is a mirror of an SVN branch, 'dcommit' may commit to the wrong | |
1011 | branch. | |
1012 | ||
1013 | If you do merge, note the following rule: 'git svn dcommit' will | |
1014 | attempt to commit on top of the SVN commit named in | |
1015 | ------------------------------------------------------------------------ | |
1016 | git log --grep=^git-svn-id: --first-parent -1 | |
1017 | ------------------------------------------------------------------------ | |
1018 | You 'must' therefore ensure that the most recent commit of the branch | |
1019 | you want to dcommit to is the 'first' parent of the merge. Chaos will | |
1020 | ensue otherwise, especially if the first parent is an older commit on | |
1021 | the same SVN branch. | |
1022 | ||
1023 | 'git clone' does not clone branches under the refs/remotes/ hierarchy or | |
1024 | any 'git svn' metadata, or config. So repositories created and managed with | |
1025 | using 'git svn' should use 'rsync' for cloning, if cloning is to be done | |
1026 | at all. | |
1027 | ||
1028 | Since 'dcommit' uses rebase internally, any Git branches you 'git push' to | |
1029 | before 'dcommit' on will require forcing an overwrite of the existing ref | |
1030 | on the remote repository. This is generally considered bad practice, | |
1031 | see the linkgit:git-push[1] documentation for details. | |
1032 | ||
1033 | Do not use the --amend option of linkgit:git-commit[1] on a change you've | |
1034 | already dcommitted. It is considered bad practice to --amend commits | |
1035 | you've already pushed to a remote repository for other users, and | |
1036 | dcommit with SVN is analogous to that. | |
1037 | ||
1038 | When cloning an SVN repository, if none of the options for describing | |
1039 | the repository layout is used (--trunk, --tags, --branches, | |
1040 | --stdlayout), 'git svn clone' will create a Git repository with | |
1041 | completely linear history, where branches and tags appear as separate | |
1042 | directories in the working copy. While this is the easiest way to get a | |
1043 | copy of a complete repository, for projects with many branches it will | |
1044 | lead to a working copy many times larger than just the trunk. Thus for | |
1045 | projects using the standard directory structure (trunk/branches/tags), | |
1046 | it is recommended to clone with option `--stdlayout`. If the project | |
1047 | uses a non-standard structure, and/or if branches and tags are not | |
1048 | required, it is easiest to only clone one directory (typically trunk), | |
1049 | without giving any repository layout options. If the full history with | |
1050 | branches and tags is required, the options `--trunk` / `--branches` / | |
1051 | `--tags` must be used. | |
1052 | ||
1053 | When using multiple --branches or --tags, 'git svn' does not automatically | |
1054 | handle name collisions (for example, if two branches from different paths have | |
1055 | the same name, or if a branch and a tag have the same name). In these cases, | |
1056 | use 'init' to set up your Git repository then, before your first 'fetch', edit | |
1057 | the $GIT_DIR/config file so that the branches and tags are associated | |
1058 | with different name spaces. For example: | |
1059 | ||
1060 | branches = stable/*:refs/remotes/svn/stable/* | |
1061 | branches = debug/*:refs/remotes/svn/debug/* | |
1062 | ||
1063 | BUGS | |
1064 | ---- | |
1065 | ||
1066 | We ignore all SVN properties except svn:executable. Any unhandled | |
1067 | properties are logged to $GIT_DIR/svn/<refname>/unhandled.log | |
1068 | ||
1069 | Renamed and copied directories are not detected by Git and hence not | |
1070 | tracked when committing to SVN. I do not plan on adding support for | |
1071 | this as it's quite difficult and time-consuming to get working for all | |
1072 | the possible corner cases (Git doesn't do it, either). Committing | |
1073 | renamed and copied files is fully supported if they're similar enough | |
1074 | for Git to detect them. | |
1075 | ||
1076 | In SVN, it is possible (though discouraged) to commit changes to a tag | |
1077 | (because a tag is just a directory copy, thus technically the same as a | |
1078 | branch). When cloning an SVN repository, 'git svn' cannot know if such a | |
1079 | commit to a tag will happen in the future. Thus it acts conservatively | |
1080 | and imports all SVN tags as branches, prefixing the tag name with 'tags/'. | |
1081 | ||
1082 | CONFIGURATION | |
1083 | ------------- | |
1084 | ||
1085 | 'git svn' stores [svn-remote] configuration information in the | |
1086 | repository $GIT_DIR/config file. It is similar the core Git | |
1087 | [remote] sections except 'fetch' keys do not accept glob | |
1088 | arguments; but they are instead handled by the 'branches' | |
1089 | and 'tags' keys. Since some SVN repositories are oddly | |
1090 | configured with multiple projects glob expansions such those | |
1091 | listed below are allowed: | |
1092 | ||
1093 | ------------------------------------------------------------------------ | |
1094 | [svn-remote "project-a"] | |
1095 | url = http://server.org/svn | |
1096 | fetch = trunk/project-a:refs/remotes/project-a/trunk | |
1097 | branches = branches/*/project-a:refs/remotes/project-a/branches/* | |
1098 | branches = branches/release_*:refs/remotes/project-a/branches/release_* | |
1099 | branches = branches/re*se:refs/remotes/project-a/branches/* | |
1100 | tags = tags/*/project-a:refs/remotes/project-a/tags/* | |
1101 | ------------------------------------------------------------------------ | |
1102 | ||
1103 | Keep in mind that the `*` (asterisk) wildcard of the local ref | |
1104 | (right of the `:`) *must* be the farthest right path component; | |
1105 | however the remote wildcard may be anywhere as long as it's an | |
1106 | independent path component (surrounded by `/` or EOL). This | |
1107 | type of configuration is not automatically created by 'init' and | |
1108 | should be manually entered with a text-editor or using 'git config'. | |
1109 | ||
1110 | Also note that only one asterisk is allowed per word. For example: | |
1111 | ||
1112 | branches = branches/re*se:refs/remotes/project-a/branches/* | |
1113 | ||
1114 | will match branches 'release', 'rese', 're123se', however | |
1115 | ||
1116 | branches = branches/re*s*e:refs/remotes/project-a/branches/* | |
1117 | ||
1118 | will produce an error. | |
1119 | ||
1120 | It is also possible to fetch a subset of branches or tags by using a | |
1121 | comma-separated list of names within braces. For example: | |
1122 | ||
1123 | ------------------------------------------------------------------------ | |
1124 | [svn-remote "huge-project"] | |
1125 | url = http://server.org/svn | |
1126 | fetch = trunk/src:refs/remotes/trunk | |
1127 | branches = branches/{red,green}/src:refs/remotes/project-a/branches/* | |
1128 | tags = tags/{1.0,2.0}/src:refs/remotes/project-a/tags/* | |
1129 | ------------------------------------------------------------------------ | |
1130 | ||
1131 | Multiple fetch, branches, and tags keys are supported: | |
1132 | ||
1133 | ------------------------------------------------------------------------ | |
1134 | [svn-remote "messy-repo"] | |
1135 | url = http://server.org/svn | |
1136 | fetch = trunk/project-a:refs/remotes/project-a/trunk | |
1137 | fetch = branches/demos/june-project-a-demo:refs/remotes/project-a/demos/june-demo | |
1138 | branches = branches/server/*:refs/remotes/project-a/branches/* | |
1139 | branches = branches/demos/2011/*:refs/remotes/project-a/2011-demos/* | |
1140 | tags = tags/server/*:refs/remotes/project-a/tags/* | |
1141 | ------------------------------------------------------------------------ | |
1142 | ||
1143 | Creating a branch in such a configuration requires disambiguating which | |
1144 | location to use using the -d or --destination flag: | |
1145 | ||
1146 | ------------------------------------------------------------------------ | |
1147 | $ git svn branch -d branches/server release-2-3-0 | |
1148 | ------------------------------------------------------------------------ | |
1149 | ||
1150 | Note that git-svn keeps track of the highest revision in which a branch | |
1151 | or tag has appeared. If the subset of branches or tags is changed after | |
1152 | fetching, then $GIT_DIR/svn/.metadata must be manually edited to remove | |
1153 | (or reset) branches-maxRev and/or tags-maxRev as appropriate. | |
1154 | ||
1155 | FILES | |
1156 | ----- | |
1157 | $GIT_DIR/svn/\**/.rev_map.*:: | |
1158 | Mapping between Subversion revision numbers and Git commit | |
1159 | names. In a repository where the noMetadata option is not set, | |
1160 | this can be rebuilt from the git-svn-id: lines that are at the | |
1161 | end of every commit (see the 'svn.noMetadata' section above for | |
1162 | details). | |
1163 | + | |
1164 | 'git svn fetch' and 'git svn rebase' automatically update the rev_map | |
1165 | if it is missing or not up to date. 'git svn reset' automatically | |
1166 | rewinds it. | |
1167 | ||
1168 | SEE ALSO | |
1169 | -------- | |
1170 | linkgit:git-rebase[1] | |
1171 | ||
1172 | GIT | |
1173 | --- | |
1174 | Part of the linkgit:git[1] suite |