]>
Commit | Line | Data |
---|---|---|
3397f9df EW |
1 | git-svn(1) |
2 | ========== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-svn - bidirectional operation between a single Subversion branch and git | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | 'git-svn' <command> [options] [arguments] | |
11 | ||
12 | DESCRIPTION | |
13 | ----------- | |
14 | git-svn is a simple conduit for changesets between a single Subversion | |
15 | branch and git. | |
16 | ||
17 | git-svn is not to be confused with git-svnimport. The were designed | |
18 | with very different goals in mind. | |
19 | ||
20 | git-svn is designed for an individual developer who wants a | |
21 | bidirectional flow of changesets between a single branch in Subversion | |
22 | and an arbitrary number of branches in git. git-svnimport is designed | |
23 | for read-only operation on repositories that match a particular layout | |
24 | (albeit the recommended one by SVN developers). | |
25 | ||
26 | For importing svn, git-svnimport is potentially more powerful when | |
27 | operating on repositories organized under the recommended | |
28 | trunk/branch/tags structure, and should be faster, too. | |
29 | ||
69f0d91e | 30 | git-svn mostly ignores the very limited view of branching that |
3397f9df EW |
31 | Subversion has. This allows git-svn to be much easier to use, |
32 | especially on repositories that are not organized in a manner that | |
33 | git-svnimport is designed for. | |
34 | ||
35 | COMMANDS | |
36 | -------- | |
37 | init:: | |
38 | Creates an empty git repository with additional metadata | |
39 | directories for git-svn. The SVN_URL must be specified | |
40 | at this point. | |
41 | ||
42 | fetch:: | |
43 | Fetch unfetched revisions from the SVN_URL we are tracking. | |
2beb3cdd | 44 | refs/heads/remotes/git-svn will be updated to the latest revision. |
3397f9df | 45 | |
2beb3cdd EW |
46 | Note: You should never attempt to modify the remotes/git-svn branch |
47 | outside of git-svn. Instead, create a branch from remotes/git-svn | |
b705ba43 | 48 | and work on that branch. Use the 'commit' command (see below) |
2beb3cdd | 49 | to write git commits back to remotes/git-svn. |
b705ba43 | 50 | |
3397f9df EW |
51 | commit:: |
52 | Commit specified commit or tree objects to SVN. This relies on | |
53 | your imported fetch data being up-to-date. This makes | |
54 | absolutely no attempts to do patching when committing to SVN, it | |
55 | simply overwrites files with those specified in the tree or | |
56 | commit. All merging is assumed to have taken place | |
57 | independently of git-svn functions. | |
58 | ||
59 | rebuild:: | |
60 | Not a part of daily usage, but this is a useful command if | |
61 | you've just cloned a repository (using git-clone) that was | |
62 | tracked with git-svn. Unfortunately, git-clone does not clone | |
63 | git-svn metadata and the svn working tree that git-svn uses for | |
64 | its operations. This rebuilds the metadata so git-svn can | |
65 | resume fetch operations. SVN_URL may be optionally specified if | |
66 | the directory/repository you're tracking has moved or changed | |
67 | protocols. | |
68 | ||
8f22562c EW |
69 | show-ignore:: |
70 | Recursively finds and lists the svn:ignore property on | |
71 | directories. The output is suitable for appending to | |
72 | the $GIT_DIR/info/exclude file. | |
73 | ||
3397f9df EW |
74 | OPTIONS |
75 | ------- | |
76 | -r <ARG>:: | |
77 | --revision <ARG>:: | |
78 | Only used with the 'fetch' command. | |
79 | ||
80 | Takes any valid -r<argument> svn would accept and passes it | |
81 | directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax | |
82 | is also supported. This is passed directly to svn, see svn | |
83 | documentation for more details. | |
84 | ||
85 | This can allow you to make partial mirrors when running fetch. | |
86 | ||
87 | -:: | |
88 | --stdin:: | |
89 | Only used with the 'commit' command. | |
90 | ||
91 | Read a list of commits from stdin and commit them in reverse | |
92 | order. Only the leading sha1 is read from each line, so | |
93 | git-rev-list --pretty=oneline output can be used. | |
94 | ||
95 | --rmdir:: | |
96 | Only used with the 'commit' command. | |
97 | ||
98 | Remove directories from the SVN tree if there are no files left | |
99 | behind. SVN can version empty directories, and they are not | |
100 | removed by default if there are no files left in them. git | |
101 | cannot version empty directories. Enabling this flag will make | |
102 | the commit to SVN act like git. | |
103 | ||
104 | -e:: | |
105 | --edit:: | |
106 | Only used with the 'commit' command. | |
107 | ||
108 | Edit the commit message before committing to SVN. This is off by | |
109 | default for objects that are commits, and forced on when committing | |
110 | tree objects. | |
111 | ||
72942938 EW |
112 | -l<num>:: |
113 | --find-copies-harder:: | |
114 | Both of these are only used with the 'commit' command. | |
115 | ||
116 | They are both passed directly to git-diff-tree see | |
117 | git-diff-tree(1) for more information. | |
118 | ||
448c81b4 EW |
119 | ADVANCED OPTIONS |
120 | ---------------- | |
69f0d91e EW |
121 | -b<refname>:: |
122 | --branch <refname>:: | |
123 | Used with 'fetch' or 'commit'. | |
124 | ||
125 | This can be used to join arbitrary git branches to remotes/git-svn | |
126 | on new commits where the tree object is equivalent. | |
127 | ||
128 | When used with different GIT_SVN_ID values, tags and branches in | |
129 | SVN can be tracked this way, as can some merges where the heads | |
130 | end up having completely equivalent content. This can even be | |
131 | used to track branches across multiple SVN _repositories_. | |
132 | ||
133 | This option may be specified multiple times, once for each | |
134 | branch. | |
135 | ||
448c81b4 EW |
136 | -i<GIT_SVN_ID>:: |
137 | --id <GIT_SVN_ID>:: | |
138 | This sets GIT_SVN_ID (instead of using the environment). See | |
139 | the section on "Tracking Multiple Repositories or Branches" for | |
140 | more information on using GIT_SVN_ID. | |
141 | ||
3397f9df EW |
142 | COMPATIBILITY OPTIONS |
143 | --------------------- | |
448c81b4 EW |
144 | --upgrade:: |
145 | Only used with the 'rebuild' command. | |
146 | ||
147 | Run this if you used an old version of git-svn that used | |
148 | 'git-svn-HEAD' instead of 'remotes/git-svn' as the branch | |
149 | for tracking the remote. | |
150 | ||
3397f9df EW |
151 | --no-ignore-externals:: |
152 | Only used with the 'fetch' and 'rebuild' command. | |
153 | ||
154 | By default, git-svn passes --ignore-externals to svn to avoid | |
155 | fetching svn:external trees into git. Pass this flag to enable | |
156 | externals tracking directly via git. | |
157 | ||
158 | Versions of svn that do not support --ignore-externals are | |
159 | automatically detected and this flag will be automatically | |
160 | enabled for them. | |
161 | ||
162 | Otherwise, do not enable this flag unless you know what you're | |
163 | doing. | |
164 | ||
165 | --no-stop-on-copy:: | |
166 | Only used with the 'fetch' command. | |
167 | ||
168 | By default, git-svn passes --stop-on-copy to avoid dealing with | |
169 | the copied/renamed branch directory problem entirely. A | |
170 | copied/renamed branch is the result of a <SVN_URL> being created | |
171 | in the past from a different source. These are problematic to | |
172 | deal with even when working purely with svn if you work inside | |
173 | subdirectories. | |
174 | ||
175 | Do not use this flag unless you know exactly what you're getting | |
176 | yourself into. You have been warned. | |
177 | ||
178 | Examples | |
179 | ~~~~~~~~ | |
180 | ||
181 | Tracking and contributing to an Subversion managed-project: | |
182 | ||
183 | # Initialize a tree (like git init-db):: | |
184 | git-svn init http://svn.foo.org/project/trunk | |
185 | # Fetch remote revisions:: | |
186 | git-svn fetch | |
187 | # Create your own branch to hack on:: | |
2beb3cdd | 188 | git checkout -b my-branch remotes/git-svn |
3397f9df EW |
189 | # Commit only the git commits you want to SVN:: |
190 | git-svn commit <tree-ish> [<tree-ish_2> ...] | |
191 | # Commit all the git commits from my-branch that don't exist in SVN:: | |
2beb3cdd | 192 | git-svn commit remotes/git-svn..my-branch |
3397f9df | 193 | # Something is committed to SVN, pull the latest into your branch:: |
2beb3cdd | 194 | git-svn fetch && git pull . remotes/git-svn |
448c81b4 | 195 | # Append svn:ignore settings to the default git exclude file:: |
8f22562c | 196 | git-svn show-ignore >> .git/info/exclude |
3397f9df EW |
197 | |
198 | DESIGN PHILOSOPHY | |
199 | ----------------- | |
200 | Merge tracking in Subversion is lacking and doing branched development | |
201 | with Subversion is cumbersome as a result. git-svn completely forgoes | |
202 | any automated merge/branch tracking on the Subversion side and leaves it | |
203 | entirely up to the user on the git side. It's simply not worth it to do | |
204 | a useful translation when the the original signal is weak. | |
205 | ||
206 | TRACKING MULTIPLE REPOSITORIES OR BRANCHES | |
207 | ------------------------------------------ | |
208 | This is for advanced users, most users should ignore this section. | |
209 | ||
210 | Because git-svn does not care about relationships between different | |
211 | branches or directories in a Subversion repository, git-svn has a simple | |
212 | hack to allow it to track an arbitrary number of related _or_ unrelated | |
213 | SVN repositories via one git repository. Simply set the GIT_SVN_ID | |
214 | environment variable to a name other other than "git-svn" (the default) | |
215 | and git-svn will ignore the contents of the $GIT_DIR/git-svn directory | |
216 | and instead do all of its work in $GIT_DIR/$GIT_SVN_ID for that | |
2beb3cdd EW |
217 | invocation. The interface branch will be remotes/$GIT_SVN_ID, instead of |
218 | remotes/git-svn. Any remotes/$GIT_SVN_ID branch should never be modified | |
b705ba43 | 219 | by the user outside of git-svn commands. |
3397f9df EW |
220 | |
221 | ADDITIONAL FETCH ARGUMENTS | |
222 | -------------------------- | |
223 | This is for advanced users, most users should ignore this section. | |
224 | ||
225 | Unfetched SVN revisions may be imported as children of existing commits | |
226 | by specifying additional arguments to 'fetch'. Additional parents may | |
227 | optionally be specified in the form of sha1 hex sums at the | |
228 | command-line. Unfetched SVN revisions may also be tied to particular | |
229 | git commits with the following syntax: | |
230 | ||
231 | svn_revision_number=git_commit_sha1 | |
232 | ||
233 | This allows you to tie unfetched SVN revision 375 to your current HEAD:: | |
234 | ||
235 | git-svn fetch 375=$(git-rev-parse HEAD) | |
236 | ||
237 | BUGS | |
238 | ---- | |
239 | If somebody commits a conflicting changeset to SVN at a bad moment | |
240 | (right before you commit) causing a conflict and your commit to fail, | |
241 | your svn working tree ($GIT_DIR/git-svn/tree) may be dirtied. The | |
242 | easiest thing to do is probably just to rm -rf $GIT_DIR/git-svn/tree and | |
243 | run 'rebuild'. | |
244 | ||
245 | We ignore all SVN properties except svn:executable. Too difficult to | |
246 | map them since we rely heavily on git write-tree being _exactly_ the | |
247 | same on both the SVN and git working trees and I prefer not to clutter | |
248 | working trees with metadata files. | |
249 | ||
250 | svn:keywords can't be ignored in Subversion (at least I don't know of | |
251 | a way to ignore them). | |
252 | ||
bbe0c9b8 EW |
253 | Renamed and copied directories are not detected by git and hence not |
254 | tracked when committing to SVN. I do not plan on adding support for | |
255 | this as it's quite difficult and time-consuming to get working for all | |
256 | the possible corner cases (git doesn't do it, either). Renamed and | |
257 | copied files are fully supported if they're similar enough for git to | |
258 | detect them. | |
259 | ||
3397f9df EW |
260 | Author |
261 | ------ | |
262 | Written by Eric Wong <normalperson@yhbt.net>. | |
263 | ||
264 | Documentation | |
265 | ------------- | |
266 | Written by Eric Wong <normalperson@yhbt.net>. |