@matheusbsbs / matheus-bagliano / commits / a836a0e172
Fork 0

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 ?