git-svn: svn (command-line) 1.0.x compatibility

[git.git] / contrib / git-svn / git-svn.txt

diff --git a/contrib/git-svn/git-svn.txt b/contrib/git-svn/git-svn.txt
index b290739..f7d3de4 100644 (file)
--- a/contrib/git-svn/git-svn.txt
+++ b/contrib/git-svn/git-svn.txt
@@ -27,7 +27,7 @@ For importing svn, git-svnimport is potentially more powerful when
 operating on repositories organized under the recommended
 trunk/branch/tags structure, and should be faster, too.
 
 operating on repositories organized under the recommended
 trunk/branch/tags structure, and should be faster, too.
 

-git-svn completely ignores the very limited view of branching that
+git-svn mostly ignores the very limited view of branching that

 Subversion has.  This allows git-svn to be much easier to use,
 especially on repositories that are not organized in a manner that
 git-svnimport is designed for.
 Subversion has.  This allows git-svn to be much easier to use,
 especially on repositories that are not organized in a manner that
 git-svnimport is designed for.


@@ -36,17 +36,22 @@ COMMANDS
 --------
 init::
        Creates an empty git repository with additional metadata
 --------
 init::
        Creates an empty git repository with additional metadata

-       directories for git-svn.  The SVN_URL must be specified
-       at this point.
+       directories for git-svn.  The Subversion URL must be specified
+       as a command-line argument.

 
 fetch::
 
 fetch::

-       Fetch unfetched revisions from the SVN_URL we are tracking.
-       refs/heads/git-svn-HEAD will be updated to the latest revision.
+       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 git-svn-HEAD branch
-       outside of git-svn.  Instead, create a branch from git-svn-HEAD
-       and work on that branch.  Use the 'commit' command (see below)
-       to write git commits back to git-svn-HEAD.
+       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 'commit'
+       command (see below) to write git commits back to
+       remotes/git-svn.
+
+       See 'Additional Fetch Arguments' if you are interested in
+       manually joining branches on commit.

 
 commit::
        Commit specified commit or tree objects to SVN.  This relies on
 
 commit::
        Commit specified commit or tree objects to SVN.  This relies on


@@ -62,9 +67,9 @@ rebuild::
        tracked with git-svn.  Unfortunately, git-clone does not clone
        git-svn metadata and the svn working tree that git-svn uses for
        its operations.  This rebuilds the metadata so git-svn can
        tracked with git-svn.  Unfortunately, git-clone does not clone
        git-svn metadata and the svn working tree that git-svn uses for
        its operations.  This rebuilds the metadata so git-svn can

-       resume fetch operations.  SVN_URL may be optionally specified if
-       the directory/repository you're tracking has moved or changed
-       protocols.
+       resume fetch operations.  A Subversion URL may be optionally
+       specified at the command-line if the directory/repository you're
+       tracking has moved or changed protocols.

 
 show-ignore::
        Recursively finds and lists the svn:ignore property on
 
 show-ignore::
        Recursively finds and lists the svn:ignore property on


@@ -101,6 +106,8 @@ OPTIONS
        cannot version empty directories.  Enabling this flag will make
        the commit to SVN act like git.
 
        cannot version empty directories.  Enabling this flag will make
        the commit to SVN act like git.
 

+       repo-config key: svn.rmdir
+

 -e::
 --edit::
        Only used with the 'commit' command.
 -e::
 --edit::
        Only used with the 'commit' command.


@@ -109,6 +116,8 @@ OPTIONS
        default for objects that are commits, and forced on when committing
        tree objects.
 
        default for objects that are commits, and forced on when committing
        tree objects.
 

+       repo-config key: svn.edit
+

 -l<num>::
 --find-copies-harder::
        Both of these are only used with the 'commit' command.
 -l<num>::
 --find-copies-harder::
        Both of these are only used with the 'commit' command.


@@ -116,8 +125,61 @@ OPTIONS
        They are both passed directly to git-diff-tree see
        git-diff-tree(1) for more information.
 
        They are both passed directly to git-diff-tree see
        git-diff-tree(1) for more information.
 

+       repo-config key: svn.l
+       repo-config key: svn.findcopiesharder
+
+-A<filename>::
+--authors-file=<filename>::
+
+       Syntax is compatible with the files used by git-svnimport and
+       git-cvsimport:
+
+------------------------------------------------------------------------
+loginname = Joe User <user@example.com>
+------------------------------------------------------------------------
+
+       If this option is specified and git-svn encounters an SVN
+       committer name that does not exist in the authors-file, git-svn
+       will abort operation. The user will then have to add the
+       appropriate entry.  Re-running the previous git-svn command
+       after the authors-file is modified should continue operation.
+
+       repo-config key: svn.authors-file
+
+ADVANCED OPTIONS
+----------------
+-b<refname>::
+--branch <refname>::
+       Used with 'fetch' or 'commit'.
+
+       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.
+
+       repo-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 Repositories or Branches" for
+       more information on using GIT_SVN_ID.
+

 COMPATIBILITY OPTIONS
 ---------------------
 COMPATIBILITY OPTIONS
 ---------------------

+--upgrade::
+       Only used with the 'rebuild' command.
+
+       Run this if you used an old version of git-svn that used
+       "git-svn-HEAD" instead of "remotes/git-svn" as the branch
+       for tracking the remote.
+

 --no-ignore-externals::
        Only used with the 'fetch' and 'rebuild' command.
 
 --no-ignore-externals::
        Only used with the 'fetch' and 'rebuild' command.
 


@@ -132,38 +194,29 @@ COMPATIBILITY OPTIONS
        Otherwise, do not enable this flag unless you know what you're
        doing.
 
        Otherwise, do not enable this flag unless you know what you're
        doing.
 

---no-stop-on-copy::
-       Only used with the 'fetch' command.
-
-       By default, git-svn passes --stop-on-copy to avoid dealing with
-       the copied/renamed branch directory problem entirely.  A
-       copied/renamed branch is the result of a <SVN_URL> being created
-       in the past from a different source.  These are problematic to
-       deal with even when working purely with svn if you work inside
-       subdirectories.
-
-       Do not use this flag unless you know exactly what you're getting
-       yourself into.  You have been warned.
+       repo-config key: svn.noignoreexternals

 
 

-Examples
-~~~~~~~~
+Basic Examples
+~~~~~~~~~~~~~~

 
 Tracking and contributing to an Subversion managed-project:
 
 
 Tracking and contributing to an Subversion managed-project:
 

-# Initialize a tree (like git init-db)::
+------------------------------------------------------------------------
+# Initialize a tree (like git init-db):

        git-svn init http://svn.foo.org/project/trunk
        git-svn init http://svn.foo.org/project/trunk

-# Fetch remote revisions::
+# Fetch remote revisions:

        git-svn fetch
        git-svn fetch

-# Create your own branch to hack on::
-       git checkout -b my-branch git-svn-HEAD
-# Commit only the git commits you want to SVN::
+# Create your own branch to hack on:
+       git checkout -b my-branch remotes/git-svn
+# Commit only the git commits you want to SVN:

        git-svn commit <tree-ish> [<tree-ish_2> ...]
        git-svn commit <tree-ish> [<tree-ish_2> ...]

-# Commit all the git commits from my-branch that don't exist in SVN::
-       git-svn commit git-svn-HEAD..my-branch
-# Something is committed to SVN, pull the latest into your branch::
-       git-svn fetch && git pull . git-svn-HEAD
+# Commit all the git commits from my-branch that don't exist in SVN:
+       git-svn commit remotes/git-svn..my-branch
+# Something is committed to SVN, pull the latest into your branch:
+       git-svn fetch && git pull . remotes/git-svn

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

+------------------------------------------------------------------------

 
 DESIGN PHILOSOPHY
 -----------------
 
 DESIGN PHILOSOPHY
 -----------------


@@ -184,8 +237,8 @@ SVN repositories via one git repository.  Simply 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/git-svn directory
 and instead do all of its work in $GIT_DIR/$GIT_SVN_ID for that
 environment variable to a name other other than "git-svn" (the default)
 and git-svn will ignore the contents of the $GIT_DIR/git-svn directory
 and instead do all of its work in $GIT_DIR/$GIT_SVN_ID for that

-invocation.  The interface branch will be $GIT_SVN_ID-HEAD, instead of
-git-svn-HEAD.  Any $GIT_SVN_ID-HEAD branch should never be modified
+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.
 
 ADDITIONAL FETCH ARGUMENTS
 by the user outside of git-svn commands.
 
 ADDITIONAL FETCH ARGUMENTS


@@ -202,7 +255,37 @@ git commits with the following syntax:
 
 This allows you to tie unfetched SVN revision 375 to your current HEAD::
 
 
 This allows you to tie unfetched SVN revision 375 to your current HEAD::
 

-       git-svn fetch 375=$(git-rev-parse HEAD)
+       `git-svn fetch 375=$(git-rev-parse HEAD)`
+
+Advanced Example: Tracking a Reorganized Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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 read this
+section.
+
+This is how Yann Dirson tracked the trunk of the ufoai directory when
+the /trunk directory of his repository was moved to /ufoai/trunk and
+he needed to continue tracking /ufoai/trunk where /trunk left off.
+
+------------------------------------------------------------------------
+       # This log message shows when the repository was reorganized:
+       r166 | ydirson | 2006-03-02 01:36:55 +0100 (Thu, 02 Mar 2006) | 1 line
+       Changed paths:
+          D /trunk
+          A /ufoai/trunk (from /trunk:165)
+
+       # First we start tracking the old revisions:
+       GIT_SVN_ID=git-oldsvn git-svn init \
+                       https://svn.sourceforge.net/svnroot/ufoai/trunk
+       GIT_SVN_ID=git-oldsvn git-svn fetch -r1:165
+
+       # And now, we continue tracking the new revisions:
+       GIT_SVN_ID=git-newsvn git-svn init \
+             https://svn.sourceforge.net/svnroot/ufoai/ufoai/trunk
+       GIT_SVN_ID=git-newsvn git-svn fetch \
+             166=`git-rev-parse refs/remotes/git-oldsvn`
+------------------------------------------------------------------------

 
 BUGS
 ----
 
 BUGS
 ----