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