X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=contrib%2Fgit-svn%2Fgit-svn.txt;h=7a6e0c4a4aee8b77f42b02a9ce66b52ff8b4696d;hb=cf1e6d1ec55264272be8b7f0c276a069d2aac69a;hp=b29073997c00944322ccc78ad5df0e1df0fc3f8f;hpb=2486927d2ec9cc05ed7589540d103382d3751c10;p=git.git diff --git a/contrib/git-svn/git-svn.txt b/contrib/git-svn/git-svn.txt index b2907399..7a6e0c4a 100644 --- 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. -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. @@ -41,12 +41,12 @@ init:: fetch:: Fetch unfetched revisions from the SVN_URL we are tracking. - refs/heads/git-svn-HEAD will be updated to the latest revision. + refs/heads/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 + 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 git-svn-HEAD. + to write git commits back to remotes/git-svn. commit:: Commit specified commit or tree objects to SVN. This relies on @@ -116,8 +116,38 @@ OPTIONS They are both passed directly to git-diff-tree see git-diff-tree(1) for more information. +ADVANCED OPTIONS +---------------- +-b:: +--branch :: + 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. + +-i:: +--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 --------------------- +--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. @@ -132,21 +162,8 @@ COMPATIBILITY OPTIONS 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 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. - -Examples -~~~~~~~~ +Basic Examples +~~~~~~~~~~~~~~ Tracking and contributing to an Subversion managed-project: @@ -155,14 +172,14 @@ Tracking and contributing to an Subversion managed-project: # Fetch remote revisions:: git-svn fetch # Create your own branch to hack on:: - git checkout -b my-branch git-svn-HEAD + git checkout -b my-branch remotes/git-svn # Commit only the git commits you want to SVN:: git-svn commit [ ...] # Commit all the git commits from my-branch that don't exist in SVN:: - git-svn commit git-svn-HEAD..my-branch + git-svn commit remotes/git-svn..my-branch # Something is committed to SVN, pull the latest into your branch:: - git-svn fetch && git pull . git-svn-HEAD -# Append svn:ignore settings to the default git exclude file: + 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 DESIGN PHILOSOPHY @@ -184,8 +201,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 -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 @@ -204,6 +221,34 @@ This allows you to tie unfetched SVN revision 375 to your current 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 ---- If somebody commits a conflicting changeset to SVN at a bad moment