From: Eric Wong Date: Thu, 15 Feb 2007 03:34:56 +0000 (-0800) Subject: git-svn: documentation updates for new functionality X-Git-Tag: v1.5.1-rc1~159 X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=a836a0e1729d1758b4085cd07fc79cb9acb64908;p=git.git 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 --- diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index d45283a53..ba3f7ce6f 100644 --- 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 -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. -'fetch':: +-T:: +--trunk=:: +-t:: +--tags=:: +-b:: +--branches=:: + 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= + 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 @@ -109,53 +125,13 @@ remotes/git-svn. repository (that has been init-ed with git-svn). The -r 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=:: --t:: ---tags=:: --b:: ---branches=:: - 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= - 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=:: Only used with the 'init' command. These are passed directly to gitlink:git-init[1]. @@ -163,14 +139,15 @@ OPTIONS -r :: --revision :: -Only used with the 'fetch' command. +Used with the 'fetch' command. -Takes any valid -r svn would accept and passes it -directly to svn. -r: 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:: ---branch :: -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:: --id :: -This sets GIT_SVN_ID (instead of using the environment). See the -section on -'<>' -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:: --svn-remote :: Specify the [svn-remote ""] 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: -'<>' ------------------------------------------------------------------------ # 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] diff --git a/git-svn.perl b/git-svn.perl index bfe5d6b97..31e536c72 100755 --- a/git-svn.perl +++ b/git-svn.perl @@ -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 [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$## ? '' : s#[:=]i$## ? '' : ''; print $fd ' ' x 21, join(', ', map { length $_ > 1 ?