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>

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index d45283a53f5d2b5c39a0b6d211ffbfdb7ada9ca8..ba3f7ce6f1ddc8d0987559737020adf169fcf588 100644 (file)
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -13,14 +13,13 @@ DESCRIPTION
 -----------
 git-svn is a simple conduit for changesets between Subversion and git.
 It is not to be confused with gitlink:git-svnimport[1], which is
 -----------
 git-svn is a simple conduit for changesets between Subversion and git.
 It is not to be confused with gitlink:git-svnimport[1], which is

-read-only and geared towards tracking multiple branches.
+read-only.

 
 git-svn was originally designed for an individual developer who wants a
 bidirectional flow of changesets between a single branch in Subversion
 and an arbitrary number of branches in git.  Since its inception,
 git-svn has gained the ability to track multiple branches in a manner
 
 git-svn was originally designed for an individual developer who wants a
 bidirectional flow of changesets between a single branch in Subversion
 and an arbitrary number of branches in git.  Since its inception,
 git-svn has gained the ability to track multiple branches in a manner

-similar to git-svnimport; but it cannot (yet) automatically detect new
-branches and tags like git-svnimport does.
+similar to git-svnimport.

 
 git-svn is especially useful when it comes to tracking repositories
 not organized in the way Subversion developers recommend (trunk,
 
 git-svn is especially useful when it comes to tracking repositories
 not organized in the way Subversion developers recommend (trunk,


@@ -31,23 +30,40 @@ COMMANDS
 --
 
 'init'::
 --
 
 'init'::

-       Creates an empty git repository with additional metadata
-       directories for git-svn.  The Subversion URL must be specified
-       as a command-line argument.  Optionally, the target directory
-       to operate on can be specified as a second argument.  Normally
-       this command initializes the current directory.
+       Initializes an empty git repository with additional
+       metadata directories for git-svn.  The Subversion URL
+       may be specified as a command-line argument, or as full
+       URL arguments to -T/-t/-b.  Optionally, the target
+       directory to operate on can be specified as a second
+       argument.  Normally this command initializes the current
+       directory.

 
 

-'fetch'::
+-T<trunk_subdir>::
+--trunk=<trunk_subdir>::
+-t<tags_subdir>::
+--tags=<tags_subdir>::
+-b<branches_subdir>::
+--branches=<branches_subdir>::
+       These are optional command-line options for init.  Each of
+       these flags can point to a relative repository path
+       (--tags=project/tags') or a full url
+       (--tags=https://foo.org/project/tags)

 
 

-Fetch unfetched revisions from the Subversion URL we are
-tracking.  refs/remotes/git-svn will be updated to the
-latest revision.
+--prefix=<prefix>
+       This allows one to specify a prefix which is prepended
+       to the names of remotes if trunk/branches/tags are
+       specified.  The prefix does not automatically include a
+       trailing slash, so be sure you include one in the
+       argument if that is what you want.  This is useful if
+       you wish to track multiple projects that share a common
+       repository.

 
 

-Note: You should never attempt to modify the remotes/git-svn
-branch outside of git-svn.  Instead, create a branch from
-remotes/git-svn and work on that branch.  Use the 'dcommit'
-command (see below) to write git commits back to
-remotes/git-svn.
+'fetch'::
+
+       Fetch unfetched revisions from the Subversion remote we are
+       tracking.  The name of the [svn-remote "..."] section in the
+       .git/config file may be specified as an optional command-line
+       argument.

 
 'dcommit'::
        Commit each diff from a specified head directly to the SVN
 
 'dcommit'::
        Commit each diff from a specified head directly to the SVN


@@ -109,53 +125,13 @@ remotes/git-svn.
        repository (that has been init-ed with git-svn).
        The -r<revision> option is required for this.
 
        repository (that has been init-ed with git-svn).
        The -r<revision> option is required for this.
 

-'graft-branches'::
-       This command attempts to detect merges/branches from already
-       imported history.  Techniques used currently include regexes,
-       file copies, and tree-matches).  This command generates (or
-       modifies) the $GIT_DIR/info/grafts file.  This command is
-       considered experimental, and inherently flawed because
-       merge-tracking in SVN is inherently flawed and inconsistent
-       across different repositories.
-
-'multi-init'::
-       This command supports git-svnimport-like command-line syntax for
-       importing repositories that are laid out as recommended by the
-       SVN folks.  This is a bit more tolerant than the git-svnimport
-       command-line syntax and doesn't require the user to figure out
-       where the repository URL ends and where the repository path
-       begins.
-
--T<trunk_subdir>::
---trunk=<trunk_subdir>::
--t<tags_subdir>::
---tags=<tags_subdir>::
--b<branches_subdir>::
---branches=<branches_subdir>::
-       These are the command-line options for multi-init.  Each of
-       these flags can point to a relative repository path
-       (--tags=project/tags') or a full url
-       (--tags=https://foo.org/project/tags)
-
---prefix=<prefix>
-       This allows one to specify a prefix which is prepended to the
-       names of remotes.  The prefix does not automatically include a
-       trailing slash, so be sure you include one in the argument if
-       that is what you want.  This is useful if you wish to track
-       multiple projects that share a common repository.
-
-'multi-fetch'::
-       This runs fetch on all known SVN branches we're tracking.  This
-       will NOT discover new branches (unlike git-svnimport), so
-       multi-init will need to be re-run (it's idempotent).
-

 --
 
 OPTIONS
 -------
 --
 
 --
 
 OPTIONS
 -------
 --
 

---shared::
+--shared[={false|true|umask|group|all|world|everybody}]::

 --template=<template_directory>::
        Only used with the 'init' command.
        These are passed directly to gitlink:git-init[1].
 --template=<template_directory>::
        Only used with the 'init' command.
        These are passed directly to gitlink:git-init[1].


@@ -163,14 +139,15 @@ OPTIONS
 -r <ARG>::
 --revision <ARG>::
 
 -r <ARG>::
 --revision <ARG>::
 

-Only used with the 'fetch' command.
+Used with the 'fetch' command.

 
 

-Takes any valid -r<argument> svn would accept and passes it
-directly to svn. -r<ARG1>:<ARG2> ranges and "{" DATE "}" syntax
-is also supported.  This is passed directly to svn, see svn
-documentation for more details.
+This allows revision ranges for partial/cauterized history
+to be supported.  $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges),
+$NUMBER:HEAD, and BASE:$NUMBER are all supported.

 
 

-This can allow you to make partial mirrors when running fetch.
+This can allow you to make partial mirrors when running fetch;
+but is generally not recommended because history will be skipped
+and lost.

 
 -::
 --stdin::
 
 -::
 --stdin::


@@ -276,36 +253,19 @@ ADVANCED OPTIONS
 ----------------
 --
 
 ----------------
 --
 

--b<refname>::
---branch <refname>::
-Used with 'fetch', 'dcommit' or 'set-tree'.
-
-This can be used to join arbitrary git branches to remotes/git-svn
-on new commits where the tree object is equivalent.
-
-When used with different GIT_SVN_ID values, tags and branches in
-SVN can be tracked this way, as can some merges where the heads
-end up having completely equivalent content.  This can even be
-used to track branches across multiple SVN _repositories_.
-
-This option may be specified multiple times, once for each
-branch.
-
-config key: svn.branch
-

 -i<GIT_SVN_ID>::
 --id <GIT_SVN_ID>::
 
 -i<GIT_SVN_ID>::
 --id <GIT_SVN_ID>::
 

-This sets GIT_SVN_ID (instead of using the environment).  See the
-section on
-'<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>'
-for more information on using GIT_SVN_ID.
+This sets GIT_SVN_ID (instead of using the environment).  This
+allows the user to override the default refname to fetch from
+when tracking a single URL.  The 'log' and 'dcommit' commands
+no longer require this switch as an argument.

 
 -R<remote name>::
 --svn-remote <remote name>::
        Specify the [svn-remote "<remote name>"] section to use,
 
 -R<remote name>::
 --svn-remote <remote name>::
        Specify the [svn-remote "<remote name>"] section to use,

-       this allows multiple repositories to be tracked.
-       Default: git-svn
+       this allows SVN multiple repositories to be tracked.
+       Default: "svn"

 
 --follow-parent::
        This is especially helpful when we're tracking a directory
 
 --follow-parent::
        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:
 
 Tracking and contributing to an entire Subversion-managed project
 (complete with a trunk, tags and branches):
 
 Tracking and contributing to an entire Subversion-managed project
 (complete with a trunk, tags and branches):

-See also:
-'<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>'

 
 ------------------------------------------------------------------------
 # Initialize a repo (like git init):
 
 ------------------------------------------------------------------------
 # Initialize a repo (like git init):

-       git-svn multi-init http://svn.foo.org/project \
-               -T trunk -b branches -t tags
+       git-svn init http://svn.foo.org/project -T trunk -b branches -t tags

 # Fetch remote revisions:
 # Fetch remote revisions:

-       git-svn multi-fetch
+       git-svn fetch

 # Create your own branch of trunk to hack on:
        git checkout -b my-trunk remotes/trunk
 # Do some work, and then commit your new changes to SVN, as well as
 # automatically updating your working HEAD:
 # Create your own branch of trunk to hack on:
        git checkout -b my-trunk remotes/trunk
 # Do some work, and then commit your new changes to SVN, as well as
 # automatically updating your working HEAD:

-       git-svn dcommit -i trunk
+       git-svn dcommit

 # Something has been committed to trunk, rebase the latest into your branch:
 # Something has been committed to trunk, rebase the latest into your branch:

-       git-svn multi-fetch && git rebase remotes/trunk
+       git-svn fetch && git rebase remotes/trunk

 # Append svn:ignore settings of trunk to the default git exclude file:
        git-svn show-ignore -i trunk >> .git/info/exclude
 # Append svn:ignore settings of trunk to the default git exclude file:
        git-svn show-ignore -i trunk >> .git/info/exclude

-# Check for new branches and tags (no arguments are needed):
-       git-svn multi-init

 ------------------------------------------------------------------------
 
 REBASE VS. PULL/MERGE
 ------------------------------------------------------------------------
 
 REBASE VS. PULL/MERGE


@@ -411,31 +366,9 @@ DESIGN PHILOSOPHY
 Merge tracking in Subversion is lacking and doing branched development
 with Subversion is cumbersome as a result.  git-svn does not do
 automated merge/branch tracking by default and leaves it entirely up to
 Merge tracking in Subversion is lacking and doing branched development
 with Subversion is cumbersome as a result.  git-svn does not do
 automated merge/branch tracking by default and leaves it entirely up to

-the user on the git side.
-
-[[tracking-multiple-repos]]
-TRACKING MULTIPLE REPOSITORIES OR BRANCHES
-------------------------------------------
-Because git-svn does not care about relationships between different
-branches or directories in a Subversion repository, git-svn has a simple
-hack to allow it to track an arbitrary number of related _or_ unrelated
-SVN repositories via one git repository.  Simply use the --id/-i flag or
-set the GIT_SVN_ID environment variable to a name other other than
-"git-svn" (the default) and git-svn will ignore the contents of the
-$GIT_DIR/svn/git-svn directory and instead do all of its work in
-$GIT_DIR/svn/$GIT_SVN_ID for that invocation.  The interface branch will
-be remotes/$GIT_SVN_ID, instead of remotes/git-svn.  Any
-remotes/$GIT_SVN_ID branch should never be modified by the user outside
-of git-svn commands.
-
-If you're tracking a directory that has moved, or otherwise been
-branched or tagged off of another directory in the repository and you
-care about the full history of the project, then you can use
-the --follow-parent option.
-
-------------------------------------------------
-       git-svn fetch --follow-parent
-------------------------------------------------
+the user on the git side.  git-svn does however follow copy
+history of the directory that it is tracking, however (much like
+how 'svn log' works).

 
 BUGS
 ----
 
 BUGS
 ----


@@ -452,6 +385,33 @@ the possible corner cases (git doesn't do it, either).  Renamed and
 copied files are fully supported if they're similar enough for git to
 detect them.
 
 copied files are fully supported if they're similar enough for git to
 detect them.
 

+CONFIGURATION
+-------------
+
+git-svn stores [svn-remote] configuration information in the
+repository .git/config file.  It is similar the core git
+[remote] sections except 'fetch' keys do not accept glob
+arguments; but they are instead handled by the 'branches'
+and 'tags' keys.  Since some SVN repositories are oddly
+configured with multiple projects glob expansions such those
+listed below are allowed:
+
+------------------------------------------------------------------------
+[svn-remote "project-a"]
+       url = http://server.org/svn
+       branches = branches/*/project-a:refs/remotes/project-a/branches/*
+       tags = tags/*/project-a:refs/remotes/project-a/tags/*
+       trunk = trunk/project-a:refs/remotes/project-a/trunk
+------------------------------------------------------------------------
+
+Keep in mind that the '*' (asterisk) wildcard of the local ref
+(left of the ':') *must* be the farthest right path component;
+however the remote wildcard may be anywhere as long as it's own
+independent path componet (surrounded by '/' or EOL).   This
+type of configuration is not automatically created by 'init' and
+should be manually entered with a text-editor or using
+gitlink:git-config[1]
+

 SEE ALSO
 --------
 gitlink:git-rebase[1]
 SEE ALSO
 --------
 gitlink:git-rebase[1]

diff --git a/git-svn.perl b/git-svn.perl
index bfe5d6b97e97cba4df1196f40e8f9bad61b91d0d..31e536c72f5a5fa72f485dda43b2a1d501c0b1d3 100755 (executable)
--- a/git-svn.perl
+++ b/git-svn.perl
@@ -114,7 +114,8 @@ BEGIN
                       # no-op, we automatically run this anyways,
                       'Migrate configuration/metadata/layout from
                        previous versions of git-svn',
                       # no-op, we automatically run this anyways,
                       'Migrate configuration/metadata/layout from
                        previous versions of git-svn',

-                       \%remote_opts ],
+                       { 'minimize' => \$Git::SVN::Migration::_minimize,
+                        %remote_opts } ],

        'log' => [ \&Git::SVN::Log::cmd_show_log, 'Show commit logs',
                        { 'limit=i' => \$Git::SVN::Log::limit,
                          'revision|r=s' => \$_revision,
        'log' => [ \&Git::SVN::Log::cmd_show_log, 'Show commit logs',
                        { 'limit=i' => \$Git::SVN::Log::limit,
                          'revision|r=s' => \$_revision,


@@ -180,9 +181,9 @@ sub usage {
 
        foreach (sort keys %cmd) {
                next if $cmd && $cmd ne $_;
 
        foreach (sort keys %cmd) {
                next if $cmd && $cmd ne $_;

+               next if /^multi-/; # don't show deprecated commands

                print $fd '  ',pack('A17',$_),$cmd{$_}->[1],"\n";
                foreach (keys %{$cmd{$_}->[2]}) {
                print $fd '  ',pack('A17',$_),$cmd{$_}->[1],"\n";
                foreach (keys %{$cmd{$_}->[2]}) {

-                       next if /^multi-/; # don't show deprecated commands

                        # prints out arguments as they should be passed:
                        my $x = s#[:=]s$## ? '<arg>' : s#[:=]i$## ? '<num>' : '';
                        print $fd ' ' x 21, join(', ', map { length $_ > 1 ?
                        # prints out arguments as they should be passed:
                        my $x = s#[:=]s$## ? '<arg>' : s#[:=]i$## ? '<num>' : '';
                        print $fd ' ' x 21, join(', ', map { length $_ > 1 ?