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>
This commit is contained in:
Eric Wong
parent
60d9c97adf
commit
a836a0e172
@ -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
|
||||
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
|
||||
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,
|
||||
@ -31,23 +30,40 @@ COMMANDS
|
||||
--
|
||||
|
||||
'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.
|
||||
|
||||
-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)
|
||||
|
||||
--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.
|
||||
|
||||
'fetch'::
|
||||
|
||||
Fetch unfetched revisions from the Subversion URL we are
|
||||
tracking. refs/remotes/git-svn will be updated to the
|
||||
latest revision.
|
||||
|
||||
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 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
|
||||
@ -109,53 +125,13 @@ remotes/git-svn.
|
||||
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
|
||||
-------
|
||||
--
|
||||
|
||||
--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].
|
||||
@ -163,14 +139,15 @@ OPTIONS
|
||||
-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::
|
||||
@ -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>::
|
||||
|
||||
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,
|
||||
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
|
||||
@ -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):
|
||||
See also:
|
||||
'<<tracking-multiple-repos,Tracking Multiple Repositories or Branches>>'
|
||||
|
||||
------------------------------------------------------------------------
|
||||
# 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:
|
||||
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:
|
||||
git-svn dcommit -i trunk
|
||||
git-svn dcommit
|
||||
# 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
|
||||
# Check for new branches and tags (no arguments are needed):
|
||||
git-svn multi-init
|
||||
------------------------------------------------------------------------
|
||||
|
||||
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
|
||||
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
|
||||
----
|
||||
@ -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.
|
||||
|
||||
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]
|
||||
|
||||
@ -114,7 +114,8 @@ my %cmd = (
|
||||
# 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,
|
||||
@ -180,9 +181,9 @@ Usage: $0 <command> [options] [arguments]\n
|
||||
|
||||
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]}) {
|
||||
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 ?
|
||||
|
||||
Loading…
Reference in New Issue
Block a user