Fix silly typo in new builtin grep
[git/git.git] / contrib / git-svn / git-svn.txt
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 mostly 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/remotes/git-svn will be updated to the latest revision.
45
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
48 and work on that branch. Use the 'commit' command (see below)
49 to write git commits back to remotes/git-svn.
50
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
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
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 repo-config key: svn.rmdir
105
106 -e::
107 --edit::
108 Only used with the 'commit' command.
109
110 Edit the commit message before committing to SVN. This is off by
111 default for objects that are commits, and forced on when committing
112 tree objects.
113
114 repo-config key: svn.edit
115
116 -l<num>::
117 --find-copies-harder::
118 Both of these are only used with the 'commit' command.
119
120 They are both passed directly to git-diff-tree see
121 git-diff-tree(1) for more information.
122
123 repo-config key: svn.l
124 repo-config key: svn.findcopiesharder
125
126 ADVANCED OPTIONS
127 ----------------
128 -b<refname>::
129 --branch <refname>::
130 Used with 'fetch' or 'commit'.
131
132 This can be used to join arbitrary git branches to remotes/git-svn
133 on new commits where the tree object is equivalent.
134
135 When used with different GIT_SVN_ID values, tags and branches in
136 SVN can be tracked this way, as can some merges where the heads
137 end up having completely equivalent content. This can even be
138 used to track branches across multiple SVN _repositories_.
139
140 This option may be specified multiple times, once for each
141 branch.
142
143 repo-config key: svn.branch
144
145 -i<GIT_SVN_ID>::
146 --id <GIT_SVN_ID>::
147 This sets GIT_SVN_ID (instead of using the environment). See
148 the section on "Tracking Multiple Repositories or Branches" for
149 more information on using GIT_SVN_ID.
150
151 COMPATIBILITY OPTIONS
152 ---------------------
153 --upgrade::
154 Only used with the 'rebuild' command.
155
156 Run this if you used an old version of git-svn that used
157 "git-svn-HEAD" instead of "remotes/git-svn" as the branch
158 for tracking the remote.
159
160 --no-ignore-externals::
161 Only used with the 'fetch' and 'rebuild' command.
162
163 By default, git-svn passes --ignore-externals to svn to avoid
164 fetching svn:external trees into git. Pass this flag to enable
165 externals tracking directly via git.
166
167 Versions of svn that do not support --ignore-externals are
168 automatically detected and this flag will be automatically
169 enabled for them.
170
171 Otherwise, do not enable this flag unless you know what you're
172 doing.
173
174 repo-config key: svn.noignoreexternals
175
176 Basic Examples
177 ~~~~~~~~~~~~~~
178
179 Tracking and contributing to an Subversion managed-project:
180
181 ------------------------------------------------------------------------
182 # Initialize a tree (like git init-db):
183 git-svn init http://svn.foo.org/project/trunk
184 # Fetch remote revisions:
185 git-svn fetch
186 # Create your own branch to hack on:
187 git checkout -b my-branch remotes/git-svn
188 # Commit only the git commits you want to SVN:
189 git-svn commit <tree-ish> [<tree-ish_2> ...]
190 # Commit all the git commits from my-branch that don't exist in SVN:
191 git-svn commit remotes/git-svn..my-branch
192 # Something is committed to SVN, pull the latest into your branch:
193 git-svn fetch && git pull . remotes/git-svn
194 # Append svn:ignore settings to the default git exclude file:
195 git-svn show-ignore >> .git/info/exclude
196 ------------------------------------------------------------------------
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
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
219 by the user outside of git-svn commands.
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 Advanced Example: Tracking a Reorganized Repository
238 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
239 If you're tracking a directory that has moved, or otherwise been
240 branched or tagged off of another directory in the repository and you
241 care about the full history of the project, then you can read this
242 section.
243
244 This is how Yann Dirson tracked the trunk of the ufoai directory when
245 the /trunk directory of his repository was moved to /ufoai/trunk and
246 he needed to continue tracking /ufoai/trunk where /trunk left off.
247
248 ------------------------------------------------------------------------
249 # This log message shows when the repository was reorganized:
250 r166 | ydirson | 2006-03-02 01:36:55 +0100 (Thu, 02 Mar 2006) | 1 line
251 Changed paths:
252 D /trunk
253 A /ufoai/trunk (from /trunk:165)
254
255 # First we start tracking the old revisions:
256 GIT_SVN_ID=git-oldsvn git-svn init \
257 https://svn.sourceforge.net/svnroot/ufoai/trunk
258 GIT_SVN_ID=git-oldsvn git-svn fetch -r1:165
259
260 # And now, we continue tracking the new revisions:
261 GIT_SVN_ID=git-newsvn git-svn init \
262 https://svn.sourceforge.net/svnroot/ufoai/ufoai/trunk
263 GIT_SVN_ID=git-newsvn git-svn fetch \
264 166=`git-rev-parse refs/remotes/git-oldsvn`
265 ------------------------------------------------------------------------
266
267 BUGS
268 ----
269 If somebody commits a conflicting changeset to SVN at a bad moment
270 (right before you commit) causing a conflict and your commit to fail,
271 your svn working tree ($GIT_DIR/git-svn/tree) may be dirtied. The
272 easiest thing to do is probably just to rm -rf $GIT_DIR/git-svn/tree and
273 run 'rebuild'.
274
275 We ignore all SVN properties except svn:executable. Too difficult to
276 map them since we rely heavily on git write-tree being _exactly_ the
277 same on both the SVN and git working trees and I prefer not to clutter
278 working trees with metadata files.
279
280 svn:keywords can't be ignored in Subversion (at least I don't know of
281 a way to ignore them).
282
283 Renamed and copied directories are not detected by git and hence not
284 tracked when committing to SVN. I do not plan on adding support for
285 this as it's quite difficult and time-consuming to get working for all
286 the possible corner cases (git doesn't do it, either). Renamed and
287 copied files are fully supported if they're similar enough for git to
288 detect them.
289
290 Author
291 ------
292 Written by Eric Wong <normalperson@yhbt.net>.
293
294 Documentation
295 -------------
296 Written by Eric Wong <normalperson@yhbt.net>.