]>
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 | ||
30 | git-svn completely ignores the very limited view of branching that | |
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. | |
44 | refs/heads/git-svn-HEAD will be updated to the latest revision. | |
45 | ||
46 | commit:: | |
47 | Commit specified commit or tree objects to SVN. This relies on | |
48 | your imported fetch data being up-to-date. This makes | |
49 | absolutely no attempts to do patching when committing to SVN, it | |
50 | simply overwrites files with those specified in the tree or | |
51 | commit. All merging is assumed to have taken place | |
52 | independently of git-svn functions. | |
53 | ||
54 | rebuild:: | |
55 | Not a part of daily usage, but this is a useful command if | |
56 | you've just cloned a repository (using git-clone) that was | |
57 | tracked with git-svn. Unfortunately, git-clone does not clone | |
58 | git-svn metadata and the svn working tree that git-svn uses for | |
59 | its operations. This rebuilds the metadata so git-svn can | |
60 | resume fetch operations. SVN_URL may be optionally specified if | |
61 | the directory/repository you're tracking has moved or changed | |
62 | protocols. | |
63 | ||
64 | OPTIONS | |
65 | ------- | |
66 | -r <ARG>:: | |
67 | --revision <ARG>:: | |
68 | Only used with the 'fetch' command. | |
69 | ||
70 | Takes any valid -r<argument> svn would accept and passes it | |
71 | directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax | |
72 | is also supported. This is passed directly to svn, see svn | |
73 | documentation for more details. | |
74 | ||
75 | This can allow you to make partial mirrors when running fetch. | |
76 | ||
77 | -:: | |
78 | --stdin:: | |
79 | Only used with the 'commit' command. | |
80 | ||
81 | Read a list of commits from stdin and commit them in reverse | |
82 | order. Only the leading sha1 is read from each line, so | |
83 | git-rev-list --pretty=oneline output can be used. | |
84 | ||
85 | --rmdir:: | |
86 | Only used with the 'commit' command. | |
87 | ||
88 | Remove directories from the SVN tree if there are no files left | |
89 | behind. SVN can version empty directories, and they are not | |
90 | removed by default if there are no files left in them. git | |
91 | cannot version empty directories. Enabling this flag will make | |
92 | the commit to SVN act like git. | |
93 | ||
94 | -e:: | |
95 | --edit:: | |
96 | Only used with the 'commit' command. | |
97 | ||
98 | Edit the commit message before committing to SVN. This is off by | |
99 | default for objects that are commits, and forced on when committing | |
100 | tree objects. | |
101 | ||
102 | COMPATIBILITY OPTIONS | |
103 | --------------------- | |
104 | --no-ignore-externals:: | |
105 | Only used with the 'fetch' and 'rebuild' command. | |
106 | ||
107 | By default, git-svn passes --ignore-externals to svn to avoid | |
108 | fetching svn:external trees into git. Pass this flag to enable | |
109 | externals tracking directly via git. | |
110 | ||
111 | Versions of svn that do not support --ignore-externals are | |
112 | automatically detected and this flag will be automatically | |
113 | enabled for them. | |
114 | ||
115 | Otherwise, do not enable this flag unless you know what you're | |
116 | doing. | |
117 | ||
118 | --no-stop-on-copy:: | |
119 | Only used with the 'fetch' command. | |
120 | ||
121 | By default, git-svn passes --stop-on-copy to avoid dealing with | |
122 | the copied/renamed branch directory problem entirely. A | |
123 | copied/renamed branch is the result of a <SVN_URL> being created | |
124 | in the past from a different source. These are problematic to | |
125 | deal with even when working purely with svn if you work inside | |
126 | subdirectories. | |
127 | ||
128 | Do not use this flag unless you know exactly what you're getting | |
129 | yourself into. You have been warned. | |
130 | ||
131 | Examples | |
132 | ~~~~~~~~ | |
133 | ||
134 | Tracking and contributing to an Subversion managed-project: | |
135 | ||
136 | # Initialize a tree (like git init-db):: | |
137 | git-svn init http://svn.foo.org/project/trunk | |
138 | # Fetch remote revisions:: | |
139 | git-svn fetch | |
140 | # Create your own branch to hack on:: | |
141 | git checkout -b my-branch git-svn-HEAD | |
142 | # Commit only the git commits you want to SVN:: | |
143 | git-svn commit <tree-ish> [<tree-ish_2> ...] | |
144 | # Commit all the git commits from my-branch that don't exist in SVN:: | |
145 | git rev-list --pretty=oneline git-svn-HEAD..my-branch | git-svn commit | |
146 | # Something is committed to SVN, pull the latest into your branch:: | |
147 | git-svn fetch && git pull . git-svn-HEAD | |
148 | ||
149 | DESIGN PHILOSOPHY | |
150 | ----------------- | |
151 | Merge tracking in Subversion is lacking and doing branched development | |
152 | with Subversion is cumbersome as a result. git-svn completely forgoes | |
153 | any automated merge/branch tracking on the Subversion side and leaves it | |
154 | entirely up to the user on the git side. It's simply not worth it to do | |
155 | a useful translation when the the original signal is weak. | |
156 | ||
157 | TRACKING MULTIPLE REPOSITORIES OR BRANCHES | |
158 | ------------------------------------------ | |
159 | This is for advanced users, most users should ignore this section. | |
160 | ||
161 | Because git-svn does not care about relationships between different | |
162 | branches or directories in a Subversion repository, git-svn has a simple | |
163 | hack to allow it to track an arbitrary number of related _or_ unrelated | |
164 | SVN repositories via one git repository. Simply set the GIT_SVN_ID | |
165 | environment variable to a name other other than "git-svn" (the default) | |
166 | and git-svn will ignore the contents of the $GIT_DIR/git-svn directory | |
167 | and instead do all of its work in $GIT_DIR/$GIT_SVN_ID for that | |
168 | invocation. | |
169 | ||
170 | ADDITIONAL FETCH ARGUMENTS | |
171 | -------------------------- | |
172 | This is for advanced users, most users should ignore this section. | |
173 | ||
174 | Unfetched SVN revisions may be imported as children of existing commits | |
175 | by specifying additional arguments to 'fetch'. Additional parents may | |
176 | optionally be specified in the form of sha1 hex sums at the | |
177 | command-line. Unfetched SVN revisions may also be tied to particular | |
178 | git commits with the following syntax: | |
179 | ||
180 | svn_revision_number=git_commit_sha1 | |
181 | ||
182 | This allows you to tie unfetched SVN revision 375 to your current HEAD:: | |
183 | ||
184 | git-svn fetch 375=$(git-rev-parse HEAD) | |
185 | ||
186 | BUGS | |
187 | ---- | |
188 | If somebody commits a conflicting changeset to SVN at a bad moment | |
189 | (right before you commit) causing a conflict and your commit to fail, | |
190 | your svn working tree ($GIT_DIR/git-svn/tree) may be dirtied. The | |
191 | easiest thing to do is probably just to rm -rf $GIT_DIR/git-svn/tree and | |
192 | run 'rebuild'. | |
193 | ||
194 | We ignore all SVN properties except svn:executable. Too difficult to | |
195 | map them since we rely heavily on git write-tree being _exactly_ the | |
196 | same on both the SVN and git working trees and I prefer not to clutter | |
197 | working trees with metadata files. | |
198 | ||
199 | svn:keywords can't be ignored in Subversion (at least I don't know of | |
200 | a way to ignore them). | |
201 | ||
202 | Author | |
203 | ------ | |
204 | Written by Eric Wong <normalperson@yhbt.net>. | |
205 | ||
206 | Documentation | |
207 | ------------- | |
208 | Written by Eric Wong <normalperson@yhbt.net>. |