]>
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 | -------- | |
10 | 'git-svn' <command> [options] [arguments] | |
11 | ||
12 | DESCRIPTION | |
13 | ----------- | |
0d313b2b EW |
14 | git-svn is a simple conduit for changesets between Subversion and git. |
15 | It is not to be confused with gitlink:git-svnimport[1], which is | |
a836a0e1 | 16 | read-only. |
3397f9df | 17 | |
0d313b2b | 18 | git-svn was originally designed for an individual developer who wants a |
3397f9df | 19 | bidirectional flow of changesets between a single branch in Subversion |
0d313b2b EW |
20 | and an arbitrary number of branches in git. Since its inception, |
21 | git-svn has gained the ability to track multiple branches in a manner | |
a836a0e1 | 22 | similar to git-svnimport. |
3397f9df | 23 | |
0d313b2b EW |
24 | git-svn is especially useful when it comes to tracking repositories |
25 | not organized in the way Subversion developers recommend (trunk, | |
26 | branches, tags directories). | |
3397f9df EW |
27 | |
28 | COMMANDS | |
29 | -------- | |
0ea4d4c9 JF |
30 | -- |
31 | ||
32 | 'init':: | |
a836a0e1 EW |
33 | Initializes an empty git repository with additional |
34 | metadata directories for git-svn. The Subversion URL | |
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 | |
a836a0e1 EW |
41 | -T<trunk_subdir>:: |
42 | --trunk=<trunk_subdir>:: | |
43 | -t<tags_subdir>:: | |
44 | --tags=<tags_subdir>:: | |
45 | -b<branches_subdir>:: | |
46 | --branches=<branches_subdir>:: | |
47 | These are optional command-line options for init. Each of | |
48 | these flags can point to a relative repository path | |
49 | (--tags=project/tags') or a full url | |
50 | (--tags=https://foo.org/project/tags) | |
3397f9df | 51 | |
0dfaf0a4 EW |
52 | --no-metadata:: |
53 | Set the 'noMetadata' option in the [svn-remote] config. | |
54 | --use-svm-props:: | |
55 | Set the 'useSvmProps' option in the [svn-remote] config. | |
56 | --use-svnsync-props:: | |
57 | Set the 'useSvnsyncProps' option in the [svn-remote] config. | |
58 | --rewrite-root=<URL>:: | |
59 | Set the 'rewriteRoot' option in the [svn-remote] config. | |
60 | ||
a836a0e1 EW |
61 | --prefix=<prefix> |
62 | This allows one to specify a prefix which is prepended | |
63 | to the names of remotes if trunk/branches/tags are | |
64 | specified. The prefix does not automatically include a | |
65 | trailing slash, so be sure you include one in the | |
66 | argument if that is what you want. This is useful if | |
67 | you wish to track multiple projects that share a common | |
68 | repository. | |
81c5a0e6 | 69 | |
a836a0e1 EW |
70 | 'fetch':: |
71 | ||
72 | Fetch unfetched revisions from the Subversion remote we are | |
73 | tracking. The name of the [svn-remote "..."] section in the | |
74 | .git/config file may be specified as an optional command-line | |
75 | argument. | |
b705ba43 | 76 | |
a81ed0b6 EW |
77 | 'clone':: |
78 | Runs 'init' and 'fetch'. It will automatically create a | |
79 | directory based on the basename of the URL passed to it; | |
80 | or if a second argument is passed; it will create a directory | |
81 | and work within that. It accepts all arguments that the | |
82 | 'init' and 'fetch' commands accept; with the exception of | |
83 | '--fetch-all'. After a repository is cloned, the 'fetch' | |
84 | command will be able to update revisions without affecting | |
85 | the working tree; and the 'rebase' command will be able | |
86 | to update the working tree with the latest changes. | |
87 | ||
88 | 'rebase':: | |
89 | This fetches revisions from the SVN parent of the current HEAD | |
90 | and rebases the current (uncommitted to SVN) work against it. | |
91 | ||
92 | This works similarly to 'svn update' or 'git-pull' except that | |
93 | it preserves linear history with 'git-rebase' instead of | |
94 | 'git-merge' for ease of dcommit-ing with git-svn. | |
95 | ||
96 | This accepts all options that 'git-svn fetch' and 'git-rebase' | |
97 | accepts. However '--fetch-all' only fetches from the current | |
98 | [svn-remote], and not all [svn-remote] definitions. | |
99 | ||
100 | Like 'git-rebase'; this requires that the working tree be clean | |
101 | and have no uncommitted changes. | |
102 | ||
b22d4497 | 103 | 'dcommit':: |
2eff1425 | 104 | Commit each diff from a specified head directly to the SVN |
b22d4497 | 105 | repository, and then rebase or reset (depending on whether or |
2eff1425 EW |
106 | not there is a diff between SVN and head). This will create |
107 | a revision in SVN for each commit in git. | |
108 | It is recommended that you run git-svn fetch and rebase (not | |
109 | pull or merge) your commits against the latest changes in the | |
110 | SVN repository. | |
dd31da2f EW |
111 | An optional command-line argument may be specified as an |
112 | alternative to HEAD. | |
3289e86e | 113 | This is advantageous over 'set-tree' (below) because it produces |
b22d4497 EW |
114 | cleaner, more linear history. |
115 | ||
e8f5d908 EW |
116 | 'log':: |
117 | This should make it easy to look up svn log messages when svn | |
118 | users refer to -r/--revision numbers. | |
119 | ||
120 | The following features from `svn log' are supported: | |
121 | ||
122 | --revision=<n>[:<n>] - is supported, non-numeric args are not: | |
123 | HEAD, NEXT, BASE, PREV, etc ... | |
124 | -v/--verbose - it's not completely compatible with | |
125 | the --verbose output in svn log, but | |
126 | reasonably close. | |
127 | --limit=<n> - is NOT the same as --max-count, | |
128 | doesn't count merged/excluded commits | |
129 | --incremental - supported | |
130 | ||
131 | New features: | |
132 | ||
133 | --show-commit - shows the git commit sha1, as well | |
134 | --oneline - our version of --pretty=oneline | |
135 | ||
136 | Any other arguments are passed directly to `git log' | |
137 | ||
3289e86e | 138 | 'set-tree':: |
e8f5d908 | 139 | You should consider using 'dcommit' instead of this command. |
3397f9df EW |
140 | Commit specified commit or tree objects to SVN. This relies on |
141 | your imported fetch data being up-to-date. This makes | |
142 | absolutely no attempts to do patching when committing to SVN, it | |
143 | simply overwrites files with those specified in the tree or | |
144 | commit. All merging is assumed to have taken place | |
145 | independently of git-svn functions. | |
146 | ||
0ea4d4c9 | 147 | 'show-ignore':: |
8f22562c EW |
148 | Recursively finds and lists the svn:ignore property on |
149 | directories. The output is suitable for appending to | |
150 | the $GIT_DIR/info/exclude file. | |
151 | ||
e8f5d908 EW |
152 | 'commit-diff':: |
153 | Commits the diff of two tree-ish arguments from the | |
23bfbb81 | 154 | command-line. This command is intended for interoperability with |
e8f5d908 EW |
155 | git-svnimport and does not rely on being inside an git-svn |
156 | init-ed repository. This command takes three arguments, (a) the | |
157 | original tree to diff against, (b) the new tree result, (c) the | |
158 | URL of the target Subversion repository. The final argument | |
159 | (URL) may be omitted if you are working from a git-svn-aware | |
160 | repository (that has been init-ed with git-svn). | |
45bf473a | 161 | The -r<revision> option is required for this. |
e8f5d908 | 162 | |
0ea4d4c9 JF |
163 | -- |
164 | ||
3397f9df EW |
165 | OPTIONS |
166 | ------- | |
0ea4d4c9 JF |
167 | -- |
168 | ||
a836a0e1 | 169 | --shared[={false|true|umask|group|all|world|everybody}]:: |
e8f5d908 EW |
170 | --template=<template_directory>:: |
171 | Only used with the 'init' command. | |
5c94f87e | 172 | These are passed directly to gitlink:git-init[1]. |
e8f5d908 | 173 | |
3397f9df EW |
174 | -r <ARG>:: |
175 | --revision <ARG>:: | |
3397f9df | 176 | |
a836a0e1 | 177 | Used with the 'fetch' command. |
0ea4d4c9 | 178 | |
a836a0e1 EW |
179 | This allows revision ranges for partial/cauterized history |
180 | to be supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges), | |
181 | $NUMBER:HEAD, and BASE:$NUMBER are all supported. | |
3397f9df | 182 | |
a836a0e1 EW |
183 | This can allow you to make partial mirrors when running fetch; |
184 | but is generally not recommended because history will be skipped | |
185 | and lost. | |
3397f9df EW |
186 | |
187 | -:: | |
188 | --stdin:: | |
3397f9df | 189 | |
3289e86e | 190 | Only used with the 'set-tree' command. |
0ea4d4c9 JF |
191 | |
192 | Read a list of commits from stdin and commit them in reverse | |
193 | order. Only the leading sha1 is read from each line, so | |
194 | git-rev-list --pretty=oneline output can be used. | |
3397f9df EW |
195 | |
196 | --rmdir:: | |
3397f9df | 197 | |
3289e86e | 198 | Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. |
0ea4d4c9 JF |
199 | |
200 | Remove directories from the SVN tree if there are no files left | |
201 | behind. SVN can version empty directories, and they are not | |
202 | removed by default if there are no files left in them. git | |
203 | cannot version empty directories. Enabling this flag will make | |
204 | the commit to SVN act like git. | |
3397f9df | 205 | |
e0d10e1c | 206 | config key: svn.rmdir |
20b1d700 | 207 | |
3397f9df EW |
208 | -e:: |
209 | --edit:: | |
3397f9df | 210 | |
3289e86e | 211 | Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. |
3397f9df | 212 | |
0ea4d4c9 JF |
213 | Edit the commit message before committing to SVN. This is off by |
214 | default for objects that are commits, and forced on when committing | |
215 | tree objects. | |
216 | ||
e0d10e1c | 217 | config key: svn.edit |
20b1d700 | 218 | |
72942938 EW |
219 | -l<num>:: |
220 | --find-copies-harder:: | |
72942938 | 221 | |
3289e86e | 222 | Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands. |
0ea4d4c9 JF |
223 | |
224 | They are both passed directly to git-diff-tree see | |
225 | gitlink:git-diff-tree[1] for more information. | |
72942938 | 226 | |
0ea4d4c9 | 227 | [verse] |
e0d10e1c TP |
228 | config key: svn.l |
229 | config key: svn.findcopiesharder | |
20b1d700 | 230 | |
81c5a0e6 EW |
231 | -A<filename>:: |
232 | --authors-file=<filename>:: | |
233 | ||
0ea4d4c9 JF |
234 | Syntax is compatible with the files used by git-svnimport and |
235 | git-cvsimport: | |
81c5a0e6 EW |
236 | |
237 | ------------------------------------------------------------------------ | |
0ea4d4c9 | 238 | loginname = Joe User <user@example.com> |
81c5a0e6 EW |
239 | ------------------------------------------------------------------------ |
240 | ||
0ea4d4c9 JF |
241 | If this option is specified and git-svn encounters an SVN |
242 | committer name that does not exist in the authors-file, git-svn | |
243 | will abort operation. The user will then have to add the | |
244 | appropriate entry. Re-running the previous git-svn command | |
245 | after the authors-file is modified should continue operation. | |
81c5a0e6 | 246 | |
e0d10e1c | 247 | config key: svn.authorsfile |
e8f5d908 EW |
248 | |
249 | -q:: | |
250 | --quiet:: | |
cec21ca7 | 251 | Make git-svn less verbose. |
e8f5d908 EW |
252 | |
253 | --repack[=<n>]:: | |
254 | --repack-flags=<flags> | |
255 | These should help keep disk usage sane for large fetches | |
256 | with many revisions. | |
257 | ||
258 | --repack takes an optional argument for the number of revisions | |
259 | to fetch before repacking. This defaults to repacking every | |
260 | 1000 commits fetched if no argument is specified. | |
261 | ||
262 | --repack-flags are passed directly to gitlink:git-repack[1]. | |
263 | ||
e0d10e1c TP |
264 | config key: svn.repack |
265 | config key: svn.repackflags | |
0ea4d4c9 | 266 | |
b22d4497 EW |
267 | -m:: |
268 | --merge:: | |
269 | -s<strategy>:: | |
270 | --strategy=<strategy>:: | |
271 | ||
a81ed0b6 | 272 | These are only used with the 'dcommit' and 'rebase' commands. |
b22d4497 EW |
273 | |
274 | Passed directly to git-rebase when using 'dcommit' if a | |
275 | 'git-reset' cannot be used (see dcommit). | |
276 | ||
277 | -n:: | |
278 | --dry-run:: | |
279 | ||
280 | This is only used with the 'dcommit' command. | |
281 | ||
282 | Print out the series of git arguments that would show | |
283 | which diffs would be committed to SVN. | |
284 | ||
0ea4d4c9 | 285 | -- |
81c5a0e6 | 286 | |
448c81b4 EW |
287 | ADVANCED OPTIONS |
288 | ---------------- | |
0ea4d4c9 JF |
289 | -- |
290 | ||
448c81b4 EW |
291 | -i<GIT_SVN_ID>:: |
292 | --id <GIT_SVN_ID>:: | |
0ea4d4c9 | 293 | |
a836a0e1 EW |
294 | This sets GIT_SVN_ID (instead of using the environment). This |
295 | allows the user to override the default refname to fetch from | |
296 | when tracking a single URL. The 'log' and 'dcommit' commands | |
297 | no longer require this switch as an argument. | |
0ea4d4c9 | 298 | |
9760adcc EW |
299 | -R<remote name>:: |
300 | --svn-remote <remote name>:: | |
301 | Specify the [svn-remote "<remote name>"] section to use, | |
a836a0e1 EW |
302 | this allows SVN multiple repositories to be tracked. |
303 | Default: "svn" | |
9760adcc | 304 | |
e8f5d908 EW |
305 | --follow-parent:: |
306 | This is especially helpful when we're tracking a directory | |
307 | that has been moved around within the repository, or if we | |
308 | started tracking a branch and never tracked the trunk it was | |
0bed5eaa EW |
309 | descended from. This feature is enabled by default, use |
310 | --no-follow-parent to disable it. | |
e8f5d908 | 311 | |
e0d10e1c | 312 | config key: svn.followparent |
e8f5d908 | 313 | |
a81ed0b6 EW |
314 | -- |
315 | CONFIG FILE-ONLY OPTIONS | |
316 | ------------------------ | |
317 | -- | |
318 | ||
0dfaf0a4 EW |
319 | svn.noMetadata:: |
320 | svn-remote.<name>.noMetadata:: | |
e8f5d908 EW |
321 | This gets rid of the git-svn-id: lines at the end of every commit. |
322 | ||
f0ecca10 EW |
323 | If you lose your .git/svn/git-svn/.rev_db file, git-svn will not |
324 | be able to rebuild it and you won't be able to fetch again, | |
325 | either. This is fine for one-shot imports. | |
e8f5d908 | 326 | |
97ae0911 EW |
327 | The 'git-svn log' command will not work on repositories using |
328 | this, either. Using this conflicts with the 'useSvmProps' | |
329 | option for (hopefully) obvious reasons. | |
330 | ||
0dfaf0a4 EW |
331 | svn.useSvmProps:: |
332 | svn-remote.<name>.useSvmProps:: | |
97ae0911 EW |
333 | This allows git-svn to re-map repository URLs and UUIDs from |
334 | mirrors created using SVN::Mirror (or svk) for metadata. | |
335 | ||
336 | If an SVN revision has a property, "svm:headrev", it is likely | |
337 | that the revision was created by SVN::Mirror (also used by SVK). | |
338 | The property contains a repository UUID and a revision. We want | |
339 | to make it look like we are mirroring the original URL, so | |
340 | introduce a helper function that returns the original identity | |
341 | URL and UUID, and use it when generating metadata in commit | |
342 | messages. | |
343 | ||
0dfaf0a4 EW |
344 | svn.useSvnsyncProps:: |
345 | svn-remote.<name>.useSvnsyncprops:: | |
a81ed0b6 EW |
346 | Similar to the useSvmProps option; this is for users |
347 | of the svnsync(1) command distributed with SVN 1.4.x and | |
348 | later. | |
349 | ||
0dfaf0a4 | 350 | svn-remote.<name>.rewriteRoot:: |
a81ed0b6 EW |
351 | This allows users to create repositories from alternate |
352 | URLs. For example, an administrator could run git-svn on the | |
353 | server locally (accessing via file://) but wish to distribute | |
354 | the repository with a public http:// or svn:// URL in the | |
355 | metadata so users of it will see the public URL. | |
356 | ||
a81ed0b6 EW |
357 | Since the noMetadata, rewriteRoot, useSvnsyncProps and useSvmProps |
358 | options all affect the metadata generated and used by git-svn; they | |
359 | *must* be set in the configuration file before any history is imported | |
360 | and these settings should never be changed once they are set. | |
361 | ||
362 | Additionally, only one of these four options can be used per-svn-remote | |
363 | section because they affect the 'git-svn-id:' metadata line. | |
e8f5d908 | 364 | |
0ea4d4c9 | 365 | -- |
448c81b4 | 366 | |
1d52aba8 EW |
367 | Basic Examples |
368 | ~~~~~~~~~~~~~~ | |
3397f9df | 369 | |
0d313b2b | 370 | Tracking and contributing to a the trunk of a Subversion-managed project: |
3397f9df | 371 | |
20b1d700 | 372 | ------------------------------------------------------------------------ |
a81ed0b6 EW |
373 | # Clone a repo (like git clone): |
374 | git-svn clone http://svn.foo.org/project/trunk | |
375 | # Enter the newly cloned directory: | |
376 | cd trunk | |
377 | # You should be on master branch, double-check with git-branch | |
378 | git branch | |
379 | # Do some work and commit locally to git: | |
380 | git commit ... | |
381 | # Something is committed to SVN, rebase your local changes against the | |
382 | # latest changes in SVN: | |
383 | git-svn rebase | |
384 | # Now commit your changes (that were committed previously using git) to SVN, | |
385 | # as well as automatically updating your working HEAD: | |
4511c899 | 386 | git-svn dcommit |
20b1d700 | 387 | # Append svn:ignore settings to the default git exclude file: |
8f22562c | 388 | git-svn show-ignore >> .git/info/exclude |
20b1d700 | 389 | ------------------------------------------------------------------------ |
3397f9df | 390 | |
0d313b2b EW |
391 | Tracking and contributing to an entire Subversion-managed project |
392 | (complete with a trunk, tags and branches): | |
0d313b2b EW |
393 | |
394 | ------------------------------------------------------------------------ | |
a81ed0b6 EW |
395 | # Clone a repo (like git clone): |
396 | git-svn clone http://svn.foo.org/project -T trunk -b branches -t tags | |
397 | # View all branches and tags you have cloned: | |
398 | git branch -r | |
399 | # Reset your master to trunk (or any other branch, replacing 'trunk' | |
400 | # with the appropriate name): | |
401 | git reset --hard remotes/trunk | |
402 | # You may only dcommit to one branch/tag/trunk at a time. The usage | |
403 | # of dcommit/rebase/show-ignore should be teh same as above. | |
0d313b2b EW |
404 | ------------------------------------------------------------------------ |
405 | ||
2eff1425 EW |
406 | REBASE VS. PULL/MERGE |
407 | --------------------- | |
2e93115e EW |
408 | |
409 | Originally, git-svn recommended that the remotes/git-svn branch be | |
2eff1425 EW |
410 | pulled or merged from. This is because the author favored |
411 | 'git-svn set-tree B' to commit a single head rather than the | |
412 | 'git-svn set-tree A..B' notation to commit multiple commits. | |
413 | ||
414 | If you use 'git-svn set-tree A..B' to commit several diffs and you do | |
415 | not have the latest remotes/git-svn merged into my-branch, you should | |
a81ed0b6 | 416 | use 'git-svn rebase' to update your work branch instead of 'git pull' or |
2eff1425 EW |
417 | 'git merge'. 'pull/merge' can cause non-linear history to be flattened |
418 | when committing into SVN, which can lead to merge commits reversing | |
419 | previous commits in SVN. | |
2e93115e | 420 | |
3397f9df EW |
421 | DESIGN PHILOSOPHY |
422 | ----------------- | |
423 | Merge tracking in Subversion is lacking and doing branched development | |
4511c899 EW |
424 | with Subversion is cumbersome as a result. git-svn does not do |
425 | automated merge/branch tracking by default and leaves it entirely up to | |
a836a0e1 EW |
426 | the user on the git side. git-svn does however follow copy |
427 | history of the directory that it is tracking, however (much like | |
428 | how 'svn log' works). | |
1d52aba8 | 429 | |
3397f9df EW |
430 | BUGS |
431 | ---- | |
e8f5d908 | 432 | |
a81ed0b6 EW |
433 | We ignore all SVN properties except svn:executable. Any unhandled |
434 | properties are logged to $GIT_DIR/svn/<refname>/unhandled.log | |
3397f9df | 435 | |
bbe0c9b8 EW |
436 | Renamed and copied directories are not detected by git and hence not |
437 | tracked when committing to SVN. I do not plan on adding support for | |
438 | this as it's quite difficult and time-consuming to get working for all | |
a81ed0b6 EW |
439 | the possible corner cases (git doesn't do it, either). Committing |
440 | renamed and copied files are fully supported if they're similar enough | |
441 | for git to detect them. | |
bbe0c9b8 | 442 | |
a836a0e1 EW |
443 | CONFIGURATION |
444 | ------------- | |
445 | ||
446 | git-svn stores [svn-remote] configuration information in the | |
447 | repository .git/config file. It is similar the core git | |
448 | [remote] sections except 'fetch' keys do not accept glob | |
449 | arguments; but they are instead handled by the 'branches' | |
450 | and 'tags' keys. Since some SVN repositories are oddly | |
451 | configured with multiple projects glob expansions such those | |
452 | listed below are allowed: | |
453 | ||
454 | ------------------------------------------------------------------------ | |
455 | [svn-remote "project-a"] | |
456 | url = http://server.org/svn | |
457 | branches = branches/*/project-a:refs/remotes/project-a/branches/* | |
458 | tags = tags/*/project-a:refs/remotes/project-a/tags/* | |
459 | trunk = trunk/project-a:refs/remotes/project-a/trunk | |
460 | ------------------------------------------------------------------------ | |
461 | ||
462 | Keep in mind that the '*' (asterisk) wildcard of the local ref | |
463 | (left of the ':') *must* be the farthest right path component; | |
464 | however the remote wildcard may be anywhere as long as it's own | |
465 | independent path componet (surrounded by '/' or EOL). This | |
466 | type of configuration is not automatically created by 'init' and | |
467 | should be manually entered with a text-editor or using | |
468 | gitlink:git-config[1] | |
469 | ||
2e93115e EW |
470 | SEE ALSO |
471 | -------- | |
472 | gitlink:git-rebase[1] | |
473 | ||
3397f9df EW |
474 | Author |
475 | ------ | |
476 | Written by Eric Wong <normalperson@yhbt.net>. | |
477 | ||
478 | Documentation | |
479 | ------------- | |
480 | Written by Eric Wong <normalperson@yhbt.net>. |