]>
Commit | Line | Data |
---|---|---|
3397f9df EW |
1 | git-svn(1) |
2 | ========== | |
3 | ||
4 | NAME | |
5 | ---- | |
c3f0baac | 6 | git-svn - Bidirectional operation between a single Subversion branch and git |
3397f9df EW |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
b1889c36 | 10 | 'git svn' <command> [options] [arguments] |
3397f9df EW |
11 | |
12 | DESCRIPTION | |
13 | ----------- | |
ba020ef5 | 14 | 'git-svn' is a simple conduit for changesets between Subversion and git. |
8cb070a4 | 15 | It provides a bidirectional flow of changes between a Subversion and a git |
1168d402 | 16 | repository. |
3397f9df | 17 | |
8cb070a4 BG |
18 | 'git-svn' can track a single Subversion branch simply by using a |
19 | URL to the branch, follow branches laid out in the Subversion recommended | |
20 | method (trunk, branches, tags directories) with the --stdlayout option, or | |
21 | follow branches in any layout with the -T/-t/-b options (see options to | |
22 | 'init' below, and also the 'clone' command). | |
3397f9df | 23 | |
8cb070a4 BG |
24 | Once tracking a Subversion branch (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. | |
3397f9df EW |
27 | |
28 | COMMANDS | |
29 | -------- | |
0ea4d4c9 JF |
30 | -- |
31 | ||
32 | 'init':: | |
a836a0e1 | 33 | Initializes an empty git repository with additional |
ba020ef5 | 34 | metadata directories for 'git-svn'. The Subversion URL |
a836a0e1 EW |
35 | may be specified as a command-line argument, or as full |
36 | URL arguments to -T/-t/-b. Optionally, the target | |
37 | directory to operate on can be specified as a second | |
38 | argument. Normally this command initializes the current | |
39 | directory. | |
3397f9df | 40 | |
cc1793e2 KW |
41 | -T<trunk_subdir>;; |
42 | --trunk=<trunk_subdir>;; | |
43 | -t<tags_subdir>;; | |
44 | --tags=<tags_subdir>;; | |
45 | -b<branches_subdir>;; | |
46 | --branches=<branches_subdir>;; | |
8f728fb9 | 47 | -s;; |
48 | --stdlayout;; | |
a836a0e1 EW |
49 | These are optional command-line options for init. Each of |
50 | these flags can point to a relative repository path | |
51 | (--tags=project/tags') or a full url | |
8f728fb9 | 52 | (--tags=https://foo.org/project/tags). The option --stdlayout is |
53 | a shorthand way of setting trunk,tags,branches as the relative paths, | |
54 | which is the Subversion default. If any of the other options are given | |
55 | as well, they take precedence. | |
cc1793e2 | 56 | --no-metadata;; |
0dfaf0a4 | 57 | Set the 'noMetadata' option in the [svn-remote] config. |
cc1793e2 | 58 | --use-svm-props;; |
0dfaf0a4 | 59 | Set the 'useSvmProps' option in the [svn-remote] config. |
cc1793e2 | 60 | --use-svnsync-props;; |
0dfaf0a4 | 61 | Set the 'useSvnsyncProps' option in the [svn-remote] config. |
cc1793e2 | 62 | --rewrite-root=<URL>;; |
0dfaf0a4 | 63 | Set the 'rewriteRoot' option in the [svn-remote] config. |
de451dff AP |
64 | --use-log-author;; |
65 | When retrieving svn commits into git (as part of fetch, rebase, or | |
66 | dcommit operations), look for the first From: or Signed-off-by: line | |
67 | in the log message and use that as the author string. | |
9e72732e AP |
68 | --add-author-from;; |
69 | When committing to svn from git (as part of commit or dcommit | |
70 | operations), if the existing log message doesn't already have a | |
71 | From: or Signed-off-by: line, append a From: line based on the | |
72 | git commit's author string. If you use this, then --use-log-author | |
73 | will retrieve a valid author string for all commits. | |
cc1793e2 | 74 | --username=<USER>;; |
a0d7fe3f SV |
75 | For transports that SVN handles authentication for (http, |
76 | https, and plain svn), specify the username. For other | |
77 | transports (eg svn+ssh://), you must include the username in | |
78 | the URL, eg svn+ssh://foo@svn.bar.com/project | |
cc1793e2 | 79 | --prefix=<prefix>;; |
a836a0e1 EW |
80 | This allows one to specify a prefix which is prepended |
81 | to the names of remotes if trunk/branches/tags are | |
82 | specified. The prefix does not automatically include a | |
83 | trailing slash, so be sure you include one in the | |
0d351e9c GP |
84 | argument if that is what you want. If --branches/-b is |
85 | specified, the prefix must include a trailing slash. | |
86 | Setting a prefix is useful if you wish to track multiple | |
87 | projects that share a common repository. | |
81c5a0e6 | 88 | |
a836a0e1 | 89 | 'fetch':: |
a836a0e1 EW |
90 | Fetch unfetched revisions from the Subversion remote we are |
91 | tracking. The name of the [svn-remote "..."] section in the | |
92 | .git/config file may be specified as an optional command-line | |
93 | argument. | |
b705ba43 | 94 | |
a81ed0b6 EW |
95 | 'clone':: |
96 | Runs 'init' and 'fetch'. It will automatically create a | |
97 | directory based on the basename of the URL passed to it; | |
98 | or if a second argument is passed; it will create a directory | |
99 | and work within that. It accepts all arguments that the | |
100 | 'init' and 'fetch' commands accept; with the exception of | |
101 | '--fetch-all'. After a repository is cloned, the 'fetch' | |
102 | command will be able to update revisions without affecting | |
103 | the working tree; and the 'rebase' command will be able | |
104 | to update the working tree with the latest changes. | |
105 | ||
106 | 'rebase':: | |
107 | This fetches revisions from the SVN parent of the current HEAD | |
108 | and rebases the current (uncommitted to SVN) work against it. | |
109 | ||
ba020ef5 JN |
110 | This works similarly to `svn update` or 'git-pull' except that |
111 | it preserves linear history with 'git-rebase' instead of | |
112 | 'git-merge' for ease of dcommiting with 'git-svn'. | |
a81ed0b6 | 113 | |
ba020ef5 | 114 | This accepts all options that 'git-svn fetch' and 'git-rebase' |
483bc4f0 | 115 | accept. However, '--fetch-all' only fetches from the current |
112f6385 | 116 | [svn-remote], and not all [svn-remote] definitions. |
a81ed0b6 | 117 | |
ba020ef5 | 118 | Like 'git-rebase'; this requires that the working tree be clean |
112f6385 | 119 | and have no uncommitted changes. |
cc1793e2 | 120 | |
dee41f3e EW |
121 | -l;; |
122 | --local;; | |
ba020ef5 | 123 | Do not fetch remotely; only run 'git-rebase' against the |
dee41f3e | 124 | last fetched commit from the upstream SVN. |
a81ed0b6 | 125 | |
b22d4497 | 126 | 'dcommit':: |
2eff1425 | 127 | Commit each diff from a specified head directly to the SVN |
b22d4497 | 128 | repository, and then rebase or reset (depending on whether or |
2eff1425 EW |
129 | not there is a diff between SVN and head). This will create |
130 | a revision in SVN for each commit in git. | |
ba020ef5 | 131 | It is recommended that you run 'git-svn' fetch and rebase (not |
2eff1425 EW |
132 | pull or merge) your commits against the latest changes in the |
133 | SVN repository. | |
dd31da2f EW |
134 | An optional command-line argument may be specified as an |
135 | alternative to HEAD. | |
3289e86e | 136 | This is advantageous over 'set-tree' (below) because it produces |
b22d4497 | 137 | cleaner, more linear history. |
171af110 KW |
138 | + |
139 | --no-rebase;; | |
140 | After committing, do not rebase or reset. | |
ba24e745 EW |
141 | --commit-url <URL>;; |
142 | Commit to this SVN URL (the full path). This is intended to | |
143 | allow existing git-svn repositories created with one transport | |
144 | method (e.g. `svn://` or `http://` for anonymous read) to be | |
145 | reused if a user is later given access to an alternate transport | |
146 | method (e.g. `svn+ssh://` or `https://`) for commit. | |
147 | ||
148 | Using this option for any other purpose (don't ask) | |
149 | is very strongly discouraged. | |
112f6385 | 150 | -- |
b22d4497 | 151 | |
e8f5d908 EW |
152 | 'log':: |
153 | This should make it easy to look up svn log messages when svn | |
154 | users refer to -r/--revision numbers. | |
112f6385 SV |
155 | + |
156 | The following features from `svn log' are supported: | |
157 | + | |
158 | -- | |
159 | --revision=<n>[:<n>];; | |
160 | is supported, non-numeric args are not: | |
161 | HEAD, NEXT, BASE, PREV, etc ... | |
162 | -v/--verbose;; | |
163 | it's not completely compatible with the --verbose | |
164 | output in svn log, but reasonably close. | |
165 | --limit=<n>;; | |
166 | is NOT the same as --max-count, doesn't count | |
167 | merged/excluded commits | |
168 | --incremental;; | |
169 | supported | |
170 | -- | |
171 | + | |
172 | New features: | |
173 | + | |
174 | -- | |
175 | --show-commit;; | |
176 | shows the git commit sha1, as well | |
177 | --oneline;; | |
178 | our version of --pretty=oneline | |
179 | -- | |
180 | + | |
a50a5c8f MV |
181 | NOTE: SVN itself only stores times in UTC and nothing else. The regular svn |
182 | client converts the UTC time to the local time (or based on the TZ= | |
183 | environment). This command has the same behaviour. | |
184 | + | |
ba020ef5 | 185 | Any other arguments are passed directly to 'git-log' |
e8f5d908 | 186 | |
6fb5375e | 187 | 'blame':: |
4be40381 SG |
188 | Show what revision and author last modified each line of a file. The |
189 | output of this mode is format-compatible with the output of | |
190 | `svn blame' by default. Like the SVN blame command, | |
191 | local uncommitted changes in the working copy are ignored; | |
192 | the version of the file in the HEAD revision is annotated. Unknown | |
ba020ef5 | 193 | arguments are passed directly to 'git-blame'. |
6fb5375e | 194 | + |
4be40381 | 195 | --git-format;; |
ba020ef5 | 196 | Produce output in the same format as 'git-blame', but with |
4be40381 SG |
197 | SVN revision numbers instead of git commit hashes. In this mode, |
198 | changes that haven't been committed to SVN (including local | |
199 | working-copy edits) are shown as revision 0. | |
6fb5375e | 200 | |
112f6385 | 201 | -- |
26e60160 AR |
202 | 'find-rev':: |
203 | When given an SVN revision number of the form 'rN', returns the | |
b3cb7e45 AR |
204 | corresponding git commit hash (this can optionally be followed by a |
205 | tree-ish to specify which branch should be searched). When given a | |
206 | tree-ish, returns the corresponding SVN revision number. | |
26e60160 | 207 | |
3289e86e | 208 | 'set-tree':: |
e8f5d908 | 209 | You should consider using 'dcommit' instead of this command. |
3397f9df EW |
210 | Commit specified commit or tree objects to SVN. This relies on |
211 | your imported fetch data being up-to-date. This makes | |
212 | absolutely no attempts to do patching when committing to SVN, it | |
213 | simply overwrites files with those specified in the tree or | |
214 | commit. All merging is assumed to have taken place | |
ba020ef5 | 215 | independently of 'git-svn' functions. |
3397f9df | 216 | |
da060c67 | 217 | 'create-ignore':: |
da060c67 GH |
218 | Recursively finds the svn:ignore property on directories and |
219 | creates matching .gitignore files. The resulting files are staged to | |
69239728 | 220 | be committed, but are not committed. Use -r/--revision to refer to a |
1168d402 | 221 | specific revision. |
da060c67 | 222 | |
0ea4d4c9 | 223 | 'show-ignore':: |
8f22562c EW |
224 | Recursively finds and lists the svn:ignore property on |
225 | directories. The output is suitable for appending to | |
226 | the $GIT_DIR/info/exclude file. | |
227 | ||
e8f5d908 EW |
228 | 'commit-diff':: |
229 | Commits the diff of two tree-ish arguments from the | |
8cb070a4 | 230 | command-line. This command does not rely on being inside an `git-svn |
483bc4f0 | 231 | init`-ed repository. This command takes three arguments, (a) the |
e8f5d908 EW |
232 | original tree to diff against, (b) the new tree result, (c) the |
233 | URL of the target Subversion repository. The final argument | |
ba020ef5 JN |
234 | (URL) may be omitted if you are working from a 'git-svn'-aware |
235 | repository (that has been `init`-ed with 'git-svn'). | |
45bf473a | 236 | The -r<revision> option is required for this. |
e8f5d908 | 237 | |
e6fefa92 DK |
238 | 'info':: |
239 | Shows information about a file or directory similar to what | |
240 | `svn info' provides. Does not currently support a -r/--revision | |
8b014d71 DK |
241 | argument. Use the --url option to output only the value of the |
242 | 'URL:' field. | |
e6fefa92 | 243 | |
69239728 GH |
244 | 'proplist':: |
245 | Lists the properties stored in the Subversion repository about a | |
246 | given file or directory. Use -r/--revision to refer to a specific | |
247 | Subversion revision. | |
248 | ||
249 | 'propget':: | |
250 | Gets the Subversion property given as the first argument, for a | |
251 | file. A specific revision can be specified with -r/--revision. | |
252 | ||
253 | 'show-externals':: | |
254 | Shows the Subversion externals. Use -r/--revision to specify a | |
255 | specific revision. | |
256 | ||
0ea4d4c9 JF |
257 | -- |
258 | ||
3397f9df EW |
259 | OPTIONS |
260 | ------- | |
0ea4d4c9 JF |
261 | -- |
262 | ||
a836a0e1 | 263 | --shared[={false|true|umask|group|all|world|everybody}]:: |
e8f5d908 EW |
264 | --template=<template_directory>:: |
265 | Only used with the 'init' command. | |
ba020ef5 | 266 | These are passed directly to 'git-init'. |
e8f5d908 | 267 | |
3397f9df EW |
268 | -r <ARG>:: |
269 | --revision <ARG>:: | |
3397f9df | 270 | |
a836a0e1 | 271 | Used with the 'fetch' command. |
0ea4d4c9 | 272 | |
a836a0e1 EW |
273 | This allows revision ranges for partial/cauterized history |
274 | to be supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges), | |
275 | $NUMBER:HEAD, and BASE:$NUMBER are all supported. | |
3397f9df | 276 | |
a836a0e1 EW |
277 | This can allow you to make partial mirrors when running fetch; |
278 | but is generally not recommended because history will be skipped | |
279 | and lost. | |
3397f9df EW |
280 | |
281 | -:: | |
282 | --stdin:: | |
3397f9df | 283 | |
3289e86e | 284 | Only used with the 'set-tree' command. |
0ea4d4c9 JF |
285 | |
286 | Read a list of commits from stdin and commit them in reverse | |
287 | order. Only the leading sha1 is read from each line, so | |
ba020ef5 | 288 | 'git-rev-list --pretty=oneline' output can be used. |
3397f9df EW |
289 | |
290 | --rmdir:: | |
3397f9df | 291 | |
3289e86e | 292 | Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. |
0ea4d4c9 JF |
293 | |
294 | Remove directories from the SVN tree if there are no files left | |
295 | behind. SVN can version empty directories, and they are not | |
296 | removed by default if there are no files left in them. git | |
297 | cannot version empty directories. Enabling this flag will make | |
298 | the commit to SVN act like git. | |
3397f9df | 299 | |
e0d10e1c | 300 | config key: svn.rmdir |
20b1d700 | 301 | |
3397f9df EW |
302 | -e:: |
303 | --edit:: | |
3397f9df | 304 | |
3289e86e | 305 | Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. |
3397f9df | 306 | |
0ea4d4c9 JF |
307 | Edit the commit message before committing to SVN. This is off by |
308 | default for objects that are commits, and forced on when committing | |
309 | tree objects. | |
310 | ||
e0d10e1c | 311 | config key: svn.edit |
20b1d700 | 312 | |
72942938 EW |
313 | -l<num>:: |
314 | --find-copies-harder:: | |
72942938 | 315 | |
3289e86e | 316 | Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. |
0ea4d4c9 | 317 | |
ba020ef5 | 318 | They are both passed directly to 'git-diff-tree'; see |
5162e697 | 319 | linkgit:git-diff-tree[1] for more information. |
72942938 | 320 | |
0ea4d4c9 | 321 | [verse] |
e0d10e1c TP |
322 | config key: svn.l |
323 | config key: svn.findcopiesharder | |
20b1d700 | 324 | |
81c5a0e6 EW |
325 | -A<filename>:: |
326 | --authors-file=<filename>:: | |
327 | ||
8cb070a4 | 328 | Syntax is compatible with the file used by 'git-cvsimport': |
81c5a0e6 EW |
329 | |
330 | ------------------------------------------------------------------------ | |
0ea4d4c9 | 331 | loginname = Joe User <user@example.com> |
81c5a0e6 EW |
332 | ------------------------------------------------------------------------ |
333 | ||
ba020ef5 JN |
334 | If this option is specified and 'git-svn' encounters an SVN |
335 | committer name that does not exist in the authors-file, 'git-svn' | |
0ea4d4c9 | 336 | will abort operation. The user will then have to add the |
ba020ef5 | 337 | appropriate entry. Re-running the previous 'git-svn' command |
0ea4d4c9 | 338 | after the authors-file is modified should continue operation. |
81c5a0e6 | 339 | |
e0d10e1c | 340 | config key: svn.authorsfile |
e8f5d908 EW |
341 | |
342 | -q:: | |
343 | --quiet:: | |
ba020ef5 | 344 | Make 'git-svn' less verbose. |
e8f5d908 EW |
345 | |
346 | --repack[=<n>]:: | |
112f6385 SV |
347 | --repack-flags=<flags>:: |
348 | ||
349 | These should help keep disk usage sane for large fetches | |
350 | with many revisions. | |
e8f5d908 | 351 | |
112f6385 SV |
352 | --repack takes an optional argument for the number of revisions |
353 | to fetch before repacking. This defaults to repacking every | |
354 | 1000 commits fetched if no argument is specified. | |
e8f5d908 | 355 | |
ba020ef5 | 356 | --repack-flags are passed directly to 'git-repack'. |
e8f5d908 | 357 | |
112f6385 | 358 | [verse] |
e0d10e1c TP |
359 | config key: svn.repack |
360 | config key: svn.repackflags | |
0ea4d4c9 | 361 | |
b22d4497 EW |
362 | -m:: |
363 | --merge:: | |
364 | -s<strategy>:: | |
365 | --strategy=<strategy>:: | |
366 | ||
a81ed0b6 | 367 | These are only used with the 'dcommit' and 'rebase' commands. |
b22d4497 | 368 | |
ba020ef5 JN |
369 | Passed directly to 'git-rebase' when using 'dcommit' if a |
370 | 'git-reset' cannot be used (see 'dcommit'). | |
b22d4497 EW |
371 | |
372 | -n:: | |
373 | --dry-run:: | |
374 | ||
7d45e146 | 375 | This can be used with the 'dcommit' and 'rebase' commands. |
b22d4497 | 376 | |
7d45e146 | 377 | For 'dcommit', print out the series of git arguments that would show |
b22d4497 EW |
378 | which diffs would be committed to SVN. |
379 | ||
7d45e146 SF |
380 | For 'rebase', display the local branch associated with the upstream svn |
381 | repository associated with the current branch and the URL of svn | |
382 | repository that will be fetched from. | |
383 | ||
0ea4d4c9 | 384 | -- |
81c5a0e6 | 385 | |
448c81b4 EW |
386 | ADVANCED OPTIONS |
387 | ---------------- | |
0ea4d4c9 JF |
388 | -- |
389 | ||
448c81b4 EW |
390 | -i<GIT_SVN_ID>:: |
391 | --id <GIT_SVN_ID>:: | |
0ea4d4c9 | 392 | |
a836a0e1 EW |
393 | This sets GIT_SVN_ID (instead of using the environment). This |
394 | allows the user to override the default refname to fetch from | |
395 | when tracking a single URL. The 'log' and 'dcommit' commands | |
396 | no longer require this switch as an argument. | |
0ea4d4c9 | 397 | |
9760adcc EW |
398 | -R<remote name>:: |
399 | --svn-remote <remote name>:: | |
400 | Specify the [svn-remote "<remote name>"] section to use, | |
a836a0e1 EW |
401 | this allows SVN multiple repositories to be tracked. |
402 | Default: "svn" | |
9760adcc | 403 | |
e8f5d908 EW |
404 | --follow-parent:: |
405 | This is especially helpful when we're tracking a directory | |
406 | that has been moved around within the repository, or if we | |
407 | started tracking a branch and never tracked the trunk it was | |
0bed5eaa EW |
408 | descended from. This feature is enabled by default, use |
409 | --no-follow-parent to disable it. | |
e8f5d908 | 410 | |
e0d10e1c | 411 | config key: svn.followparent |
e8f5d908 | 412 | |
a81ed0b6 EW |
413 | -- |
414 | CONFIG FILE-ONLY OPTIONS | |
415 | ------------------------ | |
416 | -- | |
417 | ||
0dfaf0a4 EW |
418 | svn.noMetadata:: |
419 | svn-remote.<name>.noMetadata:: | |
e8f5d908 | 420 | |
483bc4f0 | 421 | This gets rid of the 'git-svn-id:' lines at the end of every commit. |
112f6385 | 422 | |
ba020ef5 | 423 | If you lose your .git/svn/git-svn/.rev_db file, 'git-svn' will not |
112f6385 SV |
424 | be able to rebuild it and you won't be able to fetch again, |
425 | either. This is fine for one-shot imports. | |
e8f5d908 | 426 | |
ba020ef5 | 427 | The 'git-svn log' command will not work on repositories using |
112f6385 SV |
428 | this, either. Using this conflicts with the 'useSvmProps' |
429 | option for (hopefully) obvious reasons. | |
97ae0911 | 430 | |
0dfaf0a4 EW |
431 | svn.useSvmProps:: |
432 | svn-remote.<name>.useSvmProps:: | |
97ae0911 | 433 | |
ba020ef5 | 434 | This allows 'git-svn' to re-map repository URLs and UUIDs from |
112f6385 SV |
435 | mirrors created using SVN::Mirror (or svk) for metadata. |
436 | ||
437 | If an SVN revision has a property, "svm:headrev", it is likely | |
438 | that the revision was created by SVN::Mirror (also used by SVK). | |
439 | The property contains a repository UUID and a revision. We want | |
440 | to make it look like we are mirroring the original URL, so | |
441 | introduce a helper function that returns the original identity | |
442 | URL and UUID, and use it when generating metadata in commit | |
443 | messages. | |
97ae0911 | 444 | |
0dfaf0a4 EW |
445 | svn.useSvnsyncProps:: |
446 | svn-remote.<name>.useSvnsyncprops:: | |
a81ed0b6 EW |
447 | Similar to the useSvmProps option; this is for users |
448 | of the svnsync(1) command distributed with SVN 1.4.x and | |
449 | later. | |
450 | ||
0dfaf0a4 | 451 | svn-remote.<name>.rewriteRoot:: |
a81ed0b6 | 452 | This allows users to create repositories from alternate |
ba020ef5 | 453 | URLs. For example, an administrator could run 'git-svn' on the |
a81ed0b6 EW |
454 | server locally (accessing via file://) but wish to distribute |
455 | the repository with a public http:// or svn:// URL in the | |
456 | metadata so users of it will see the public URL. | |
457 | ||
3b2bbe9b JK |
458 | -- |
459 | ||
a81ed0b6 | 460 | Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps |
ba020ef5 | 461 | options all affect the metadata generated and used by 'git-svn'; they |
a81ed0b6 EW |
462 | *must* be set in the configuration file before any history is imported |
463 | and these settings should never be changed once they are set. | |
464 | ||
465 | Additionally, only one of these four options can be used per-svn-remote | |
466 | section because they affect the 'git-svn-id:' metadata line. | |
e8f5d908 | 467 | |
448c81b4 | 468 | |
112f6385 SV |
469 | BASIC EXAMPLES |
470 | -------------- | |
3397f9df | 471 | |
06ada152 | 472 | Tracking and contributing to the trunk of a Subversion-managed project: |
3397f9df | 473 | |
20b1d700 | 474 | ------------------------------------------------------------------------ |
a81ed0b6 | 475 | # Clone a repo (like git clone): |
2670ddce | 476 | git svn clone http://svn.example.com/project/trunk |
a81ed0b6 EW |
477 | # Enter the newly cloned directory: |
478 | cd trunk | |
479 | # You should be on master branch, double-check with git-branch | |
480 | git branch | |
481 | # Do some work and commit locally to git: | |
482 | git commit ... | |
483 | # Something is committed to SVN, rebase your local changes against the | |
484 | # latest changes in SVN: | |
b1889c36 | 485 | git svn rebase |
a81ed0b6 EW |
486 | # Now commit your changes (that were committed previously using git) to SVN, |
487 | # as well as automatically updating your working HEAD: | |
b1889c36 | 488 | git svn dcommit |
20b1d700 | 489 | # Append svn:ignore settings to the default git exclude file: |
b1889c36 | 490 | git svn show-ignore >> .git/info/exclude |
20b1d700 | 491 | ------------------------------------------------------------------------ |
3397f9df | 492 | |
0d313b2b EW |
493 | Tracking and contributing to an entire Subversion-managed project |
494 | (complete with a trunk, tags and branches): | |
0d313b2b EW |
495 | |
496 | ------------------------------------------------------------------------ | |
a81ed0b6 | 497 | # Clone a repo (like git clone): |
2670ddce | 498 | git svn clone http://svn.example.com/project -T trunk -b branches -t tags |
a81ed0b6 EW |
499 | # View all branches and tags you have cloned: |
500 | git branch -r | |
501 | # Reset your master to trunk (or any other branch, replacing 'trunk' | |
502 | # with the appropriate name): | |
503 | git reset --hard remotes/trunk | |
504 | # You may only dcommit to one branch/tag/trunk at a time. The usage | |
20f50f16 | 505 | # of dcommit/rebase/show-ignore should be the same as above. |
0d313b2b EW |
506 | ------------------------------------------------------------------------ |
507 | ||
ba020ef5 | 508 | The initial 'git-svn clone' can be quite time-consuming |
7d4aef40 AR |
509 | (especially for large Subversion repositories). If multiple |
510 | people (or one person with multiple machines) want to use | |
ba020ef5 JN |
511 | 'git-svn' to interact with the same Subversion repository, you can |
512 | do the initial 'git-svn clone' to a repository on a server and | |
513 | have each person clone that repository with 'git-clone': | |
7d4aef40 AR |
514 | |
515 | ------------------------------------------------------------------------ | |
516 | # Do the initial import on a server | |
2670ddce | 517 | ssh server "cd /pub && git svn clone http://svn.example.com/project |
2b0d1033 SV |
518 | # Clone locally - make sure the refs/remotes/ space matches the server |
519 | mkdir project | |
520 | cd project | |
b1889c36 | 521 | git init |
2b0d1033 | 522 | git remote add origin server:/pub/project |
762656e0 | 523 | git config --add remote.origin.fetch '+refs/remotes/*:refs/remotes/*' |
2b0d1033 | 524 | git fetch |
7d4aef40 | 525 | # Initialize git-svn locally (be sure to use the same URL and -T/-b/-t options as were used on server) |
2670ddce | 526 | git svn init http://svn.example.com/project |
7d4aef40 | 527 | # Pull the latest changes from Subversion |
b1889c36 | 528 | git svn rebase |
7d4aef40 AR |
529 | ------------------------------------------------------------------------ |
530 | ||
2eff1425 EW |
531 | REBASE VS. PULL/MERGE |
532 | --------------------- | |
2e93115e | 533 | |
ba020ef5 | 534 | Originally, 'git-svn' recommended that the 'remotes/git-svn' branch be |
2eff1425 | 535 | pulled or merged from. This is because the author favored |
483bc4f0 JN |
536 | `git svn set-tree B` to commit a single head rather than the |
537 | `git svn set-tree A..B` notation to commit multiple commits. | |
2eff1425 | 538 | |
483bc4f0 | 539 | If you use `git svn set-tree A..B` to commit several diffs and you do |
2eff1425 | 540 | not have the latest remotes/git-svn merged into my-branch, you should |
483bc4f0 JN |
541 | use `git svn rebase` to update your work branch instead of `git pull` or |
542 | `git merge`. `pull`/`merge' can cause non-linear history to be flattened | |
2eff1425 EW |
543 | when committing into SVN, which can lead to merge commits reversing |
544 | previous commits in SVN. | |
2e93115e | 545 | |
3397f9df EW |
546 | DESIGN PHILOSOPHY |
547 | ----------------- | |
548 | Merge tracking in Subversion is lacking and doing branched development | |
ba020ef5 | 549 | with Subversion can be cumbersome as a result. While 'git-svn' can track |
bd43098c EW |
550 | copy history (including branches and tags) for repositories adopting a |
551 | standard layout, it cannot yet represent merge history that happened | |
552 | inside git back upstream to SVN users. Therefore it is advised that | |
553 | users keep history as linear as possible inside git to ease | |
554 | compatibility with SVN (see the CAVEATS section below). | |
1d52aba8 | 555 | |
aabb2e51 EW |
556 | CAVEATS |
557 | ------- | |
558 | ||
559 | For the sake of simplicity and interoperating with a less-capable system | |
ba020ef5 | 560 | (SVN), it is recommended that all 'git-svn' users clone, fetch and dcommit |
5833d730 | 561 | directly from the SVN server, and avoid all 'git-clone'/'pull'/'merge'/'push' |
aabb2e51 EW |
562 | operations between git repositories and branches. The recommended |
563 | method of exchanging code between git branches and users is | |
ba020ef5 | 564 | 'git-format-patch' and 'git-am', or just 'dcommit'ing to the SVN repository. |
aabb2e51 | 565 | |
ba020ef5 | 566 | Running 'git-merge' or 'git-pull' is NOT recommended on a branch you |
483bc4f0 | 567 | plan to 'dcommit' from. Subversion does not represent merges in any |
aabb2e51 EW |
568 | reasonable or useful fashion; so users using Subversion cannot see any |
569 | merges you've made. Furthermore, if you merge or pull from a git branch | |
483bc4f0 | 570 | that is a mirror of an SVN branch, 'dcommit' may commit to the wrong |
aabb2e51 EW |
571 | branch. |
572 | ||
ba020ef5 JN |
573 | 'git-clone' does not clone branches under the refs/remotes/ hierarchy or |
574 | any 'git-svn' metadata, or config. So repositories created and managed with | |
2fd02c92 | 575 | using 'git-svn' should use 'rsync' for cloning, if cloning is to be done |
aabb2e51 EW |
576 | at all. |
577 | ||
ba020ef5 | 578 | Since 'dcommit' uses rebase internally, any git branches you 'git-push' to |
483bc4f0 | 579 | before 'dcommit' on will require forcing an overwrite of the existing ref |
aabb2e51 | 580 | on the remote repository. This is generally considered bad practice, |
483bc4f0 | 581 | see the linkgit:git-push[1] documentation for details. |
aabb2e51 | 582 | |
483bc4f0 | 583 | Do not use the --amend option of linkgit:git-commit[1] on a change you've |
aabb2e51 EW |
584 | already dcommitted. It is considered bad practice to --amend commits |
585 | you've already pushed to a remote repository for other users, and | |
586 | dcommit with SVN is analogous to that. | |
587 | ||
3397f9df EW |
588 | BUGS |
589 | ---- | |
e8f5d908 | 590 | |
a81ed0b6 EW |
591 | We ignore all SVN properties except svn:executable. Any unhandled |
592 | properties are logged to $GIT_DIR/svn/<refname>/unhandled.log | |
3397f9df | 593 | |
bbe0c9b8 EW |
594 | Renamed and copied directories are not detected by git and hence not |
595 | tracked when committing to SVN. I do not plan on adding support for | |
596 | this as it's quite difficult and time-consuming to get working for all | |
a81ed0b6 EW |
597 | the possible corner cases (git doesn't do it, either). Committing |
598 | renamed and copied files are fully supported if they're similar enough | |
599 | for git to detect them. | |
bbe0c9b8 | 600 | |
a836a0e1 EW |
601 | CONFIGURATION |
602 | ------------- | |
603 | ||
ba020ef5 | 604 | 'git-svn' stores [svn-remote] configuration information in the |
a836a0e1 EW |
605 | repository .git/config file. It is similar the core git |
606 | [remote] sections except 'fetch' keys do not accept glob | |
607 | arguments; but they are instead handled by the 'branches' | |
608 | and 'tags' keys. Since some SVN repositories are oddly | |
609 | configured with multiple projects glob expansions such those | |
610 | listed below are allowed: | |
611 | ||
612 | ------------------------------------------------------------------------ | |
613 | [svn-remote "project-a"] | |
614 | url = http://server.org/svn | |
615 | branches = branches/*/project-a:refs/remotes/project-a/branches/* | |
616 | tags = tags/*/project-a:refs/remotes/project-a/tags/* | |
617 | trunk = trunk/project-a:refs/remotes/project-a/trunk | |
618 | ------------------------------------------------------------------------ | |
619 | ||
620 | Keep in mind that the '*' (asterisk) wildcard of the local ref | |
d37a8de0 | 621 | (right of the ':') *must* be the farthest right path component; |
a836a0e1 | 622 | however the remote wildcard may be anywhere as long as it's own |
02783075 | 623 | independent path component (surrounded by '/' or EOL). This |
a836a0e1 | 624 | type of configuration is not automatically created by 'init' and |
ba020ef5 | 625 | should be manually entered with a text-editor or using 'git-config'. |
a836a0e1 | 626 | |
2e93115e EW |
627 | SEE ALSO |
628 | -------- | |
5162e697 | 629 | linkgit:git-rebase[1] |
2e93115e | 630 | |
3397f9df EW |
631 | Author |
632 | ------ | |
633 | Written by Eric Wong <normalperson@yhbt.net>. | |
634 | ||
635 | Documentation | |
636 | ------------- | |
637 | Written by Eric Wong <normalperson@yhbt.net>. |