git-svn: documentation updates for new functionality
Force the showing of the --minimize flag as an option in the 'migrate' help. Also, fix the usage function to correctly filter out the deprecated aliases. Signed-off-by: Eric Wong <normalperson@yhbt.net>
Eric Wong committed
Feb 14, 2007 at 19:34 UTC
a836a0e1729d1758b4085cd07fc79cb9acb64908
2 files changed
+84
-123
Documentation/git-svn.txt
+81
-121
@@ -13,14 +13,13 @@ DESCRIPTION
13
-----------
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
16
-read-only and geared towards tracking multiple branches.
16
+read-only.
17
18
git-svn was originally designed for an individual developer who wants a
19
bidirectional flow of changesets between a single branch in Subversion
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
22
-similar to git-svnimport; but it cannot (yet) automatically detect new
23
-branches and tags like git-svnimport does.
22
+similar to git-svnimport.
23
24
git-svn is especially useful when it comes to tracking repositories
25
not organized in the way Subversion developers recommend (trunk,
@@ -31,23 +30,40 @@ COMMANDS
30
--
31
32
'init'::
34
- Creates an empty git repository with additional metadata
35
- directories for git-svn. The Subversion URL must be specified
36
- as a command-line argument. Optionally, the target directory
37
- to operate on can be specified as a second argument. Normally
38
- this command initializes the current directory.
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.
40
40
-'fetch'::
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)
51
42
-Fetch unfetched revisions from the Subversion URL we are
43
-tracking. refs/remotes/git-svn will be updated to the
44
-latest revision.
52
+--prefix=<prefix>
53
+ This allows one to specify a prefix which is prepended
54
+ to the names of remotes if trunk/branches/tags are
55
+ specified. The prefix does not automatically include a
56
+ trailing slash, so be sure you include one in the
57
+ argument if that is what you want. This is useful if
58
+ you wish to track multiple projects that share a common
59
+ repository.
60
46
-Note: You should never attempt to modify the remotes/git-svn
47
-branch outside of git-svn. Instead, create a branch from
48
-remotes/git-svn and work on that branch. Use the 'dcommit'
49
-command (see below) to write git commits back to
50
-remotes/git-svn.
61
+'fetch'::
62
+
63
+ Fetch unfetched revisions from the Subversion remote we are
64
+ tracking. The name of the [svn-remote "..."] section in the
65
+ .git/config file may be specified as an optional command-line
66
+ argument.
67
68
'dcommit'::
69
Commit each diff from a specified head directly to the SVN
@@ -109,53 +125,13 @@ remotes/git-svn.
125
repository (that has been init-ed with git-svn).
126
The -r<revision> option is required for this.
127
112
-'graft-branches'::
113
- This command attempts to detect merges/branches from already
114
- imported history. Techniques used currently include regexes,
115
- file copies, and tree-matches). This command generates (or
116
- modifies) the $GIT_DIR/info/grafts file. This command is
117
- considered experimental, and inherently flawed because
118
- merge-tracking in SVN is inherently flawed and inconsistent
119
- across different repositories.
120
-
121
-'multi-init'::
122
- This command supports git-svnimport-like command-line syntax for
123
- importing repositories that are laid out as recommended by the
124
- SVN folks. This is a bit more tolerant than the git-svnimport
125
- command-line syntax and doesn't require the user to figure out
126
- where the repository URL ends and where the repository path
127
- begins.
128
-
129
--T<trunk_subdir>::
130
---trunk=<trunk_subdir>::
131
--t<tags_subdir>::
132
---tags=<tags_subdir>::
133
--b<branches_subdir>::
134
---branches=<branches_subdir>::
135
- These are the command-line options for multi-init. Each of
136
- these flags can point to a relative repository path
137
- (--tags=project/tags') or a full url
138
- (--tags=https://foo.org/project/tags)
139
-
140
---prefix=<prefix>
141
- This allows one to specify a prefix which is prepended to the
142
- names of remotes. The prefix does not automatically include a
143
- trailing slash, so be sure you include one in the argument if
144
- that is what you want. This is useful if you wish to track
145
- multiple projects that share a common repository.
146
-
147
-'multi-fetch'::
148
- This runs fetch on all known SVN branches we're tracking. This
149
- will NOT discover new branches (unlike git-svnimport), so
150
- multi-init will need to be re-run (it's idempotent).
151
-
128
--
129
130
OPTIONS
131
-------
132
--
133
158
---shared::
134
+--shared[={false|true|umask|group|all|world|everybody}]::
135
--template=<template_directory>::
136
Only used with the 'init' command.
137
These are passed directly to gitlink:git-init[1].
@@ -163,14 +139,15 @@ OPTIONS
139
-r <ARG>::
140
--revision <ARG>::
141
166
-Only used with the 'fetch' command.
142
+Used with the 'fetch' command.
143
168
-Takes any valid -r<argument> svn would accept and passes it
169
-directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax
170
-is also supported. This is passed directly to svn, see svn
171
-documentation for more details.
144
+This allows revision ranges for partial/cauterized history
145
+to be supported. $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges),
146
+$NUMBER:HEAD, and BASE:$NUMBER are all supported.
147
173
-This can allow you to make partial mirrors when running fetch.
148
+This can allow you to make partial mirrors when running fetch;
149
+but is generally not recommended because history will be skipped
150
+and lost.
151
152
-::
153
--stdin::
@@ -276,36 +253,19 @@ ADVANCED OPTIONS
253
----------------
254
--
255
279
--b<refname>::
280
---branch <refname>::
281
-Used with 'fetch', 'dcommit' or 'set-tree'.
282
-
283
-This can be used to join arbitrary git branches to remotes/git-svn
284
-on new commits where the tree object is equivalent.
285
-
286
-When used with different GIT_SVN_ID values, tags and branches in
287
-SVN can be tracked this way, as can some merges where the heads
288
-end up having completely equivalent content. This can even be
289
-used to track branches across multiple SVN _repositories_.
290
-
291
-This option may be specified multiple times, once for each
292
-branch.
293
-
294
-config key: svn.branch
295
-
256
-i<GIT_SVN_ID>::
257
--id <GIT_SVN_ID>::
258
299
-This sets GIT_SVN_ID (instead of using the environment). See the
300
-section on
301
-'<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>'
302
-for more information on using GIT_SVN_ID.
259
+This sets GIT_SVN_ID (instead of using the environment). This
260
+allows the user to override the default refname to fetch from
261
+when tracking a single URL. The 'log' and 'dcommit' commands
262
+no longer require this switch as an argument.
263
264
-R<remote name>::
265
--svn-remote <remote name>::
266
Specify the [svn-remote "<remote name>"] section to use,
307
- this allows multiple repositories to be tracked.
308
- Default: git-svn
267
+ this allows SVN multiple repositories to be tracked.
268
+ Default: "svn"
269
270
--follow-parent::
271
This is especially helpful when we're tracking a directory
@@ -369,26 +329,21 @@ Tracking and contributing to a the trunk of a Subversion-managed project:
329
330
Tracking and contributing to an entire Subversion-managed project
331
(complete with a trunk, tags and branches):
372
-See also:
373
-'<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>'
332
333
------------------------------------------------------------------------
334
# Initialize a repo (like git init):
377
- git-svn multi-init http://svn.foo.org/project \
378
- -T trunk -b branches -t tags
335
+ git-svn init http://svn.foo.org/project -T trunk -b branches -t tags
336
# Fetch remote revisions:
380
- git-svn multi-fetch
337
+ git-svn fetch
338
# Create your own branch of trunk to hack on:
339
git checkout -b my-trunk remotes/trunk
340
# Do some work, and then commit your new changes to SVN, as well as
341
# automatically updating your working HEAD:
385
- git-svn dcommit -i trunk
342
+ git-svn dcommit
343
# Something has been committed to trunk, rebase the latest into your branch:
387
- git-svn multi-fetch && git rebase remotes/trunk
344
+ git-svn fetch && git rebase remotes/trunk
345
# Append svn:ignore settings of trunk to the default git exclude file:
346
git-svn show-ignore -i trunk >> .git/info/exclude
390
-# Check for new branches and tags (no arguments are needed):
391
- git-svn multi-init
347
------------------------------------------------------------------------
348
349
REBASE VS. PULL/MERGE
@@ -411,31 +366,9 @@ DESIGN PHILOSOPHY
366
Merge tracking in Subversion is lacking and doing branched development
367
with Subversion is cumbersome as a result. git-svn does not do
368
automated merge/branch tracking by default and leaves it entirely up to
414
-the user on the git side.
415
-
416
-[[tracking-multiple-repos]]
417
-TRACKING MULTIPLE REPOSITORIES OR BRANCHES
418
-------------------------------------------
419
-Because git-svn does not care about relationships between different
420
-branches or directories in a Subversion repository, git-svn has a simple
421
-hack to allow it to track an arbitrary number of related _or_ unrelated
422
-SVN repositories via one git repository. Simply use the --id/-i flag or
423
-set the GIT_SVN_ID environment variable to a name other other than
424
-"git-svn" (the default) and git-svn will ignore the contents of the
425
-$GIT_DIR/svn/git-svn directory and instead do all of its work in
426
-$GIT_DIR/svn/$GIT_SVN_ID for that invocation. The interface branch will
427
-be remotes/$GIT_SVN_ID, instead of remotes/git-svn. Any
428
-remotes/$GIT_SVN_ID branch should never be modified by the user outside
429
-of git-svn commands.
430
-
431
-If you're tracking a directory that has moved, or otherwise been
432
-branched or tagged off of another directory in the repository and you
433
-care about the full history of the project, then you can use
434
-the --follow-parent option.
435
-
436
-------------------------------------------------
437
- git-svn fetch --follow-parent
438
-------------------------------------------------
369
+the user on the git side. git-svn does however follow copy
370
+history of the directory that it is tracking, however (much like
371
+how 'svn log' works).
372
373
BUGS
374
----
@@ -452,6 +385,33 @@ the possible corner cases (git doesn't do it, either). Renamed and
385
copied files are fully supported if they're similar enough for git to
386
detect them.
387
388
+CONFIGURATION
389
+-------------
390
+
391
+git-svn stores [svn-remote] configuration information in the
392
+repository .git/config file. It is similar the core git
393
+[remote] sections except 'fetch' keys do not accept glob
394
+arguments; but they are instead handled by the 'branches'
395
+and 'tags' keys. Since some SVN repositories are oddly
396
+configured with multiple projects glob expansions such those
397
+listed below are allowed:
398
+
399
+------------------------------------------------------------------------
400
+[svn-remote "project-a"]
401
+ url = http://server.org/svn
402
+ branches = branches/*/project-a:refs/remotes/project-a/branches/*
403
+ tags = tags/*/project-a:refs/remotes/project-a/tags/*
404
+ trunk = trunk/project-a:refs/remotes/project-a/trunk
405
+------------------------------------------------------------------------
406
+
407
+Keep in mind that the '*' (asterisk) wildcard of the local ref
408
+(left of the ':') *must* be the farthest right path component;
409
+however the remote wildcard may be anywhere as long as it's own
410
+independent path componet (surrounded by '/' or EOL). This
411
+type of configuration is not automatically created by 'init' and
412
+should be manually entered with a text-editor or using
413
+gitlink:git-config[1]
414
+
415
SEE ALSO
416
--------
417
gitlink:git-rebase[1]
git-svn.perl
+3
-2
@@ -114,7 +114,8 @@ my %cmd = (
114
# no-op, we automatically run this anyways,
115
'Migrate configuration/metadata/layout from
116
previous versions of git-svn',
117
- \%remote_opts ],
117
+ { 'minimize' => \$Git::SVN::Migration::_minimize,
118
+ %remote_opts } ],
119
'log' => [ \&Git::SVN::Log::cmd_show_log, 'Show commit logs',
120
{ 'limit=i' => \$Git::SVN::Log::limit,
121
'revision|r=s' => \$_revision,
@@ -180,9 +181,9 @@ Usage: $0 <command> [options] [arguments]\n
181
182
foreach (sort keys %cmd) {
183
next if $cmd && $cmd ne $_;
184
+ next if /^multi-/; # don't show deprecated commands
185
print $fd ' ',pack('A17',$_),$cmd{$_}->[1],"\n";
186
foreach (keys %{$cmd{$_}->[2]}) {
185
- next if /^multi-/; # don't show deprecated commands
187
# prints out arguments as they should be passed:
188
my $x = s#[:=]s$## ? '<arg>' : s#[:=]i$## ? '<num>' : '';
189
print $fd ' ' x 21, join(', ', map { length $_ > 1 ?