core.logallrefupdates thinko-fix

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

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 14bdef2939066625da2e8d2ca3c90601411aad4f..1cfa3e342cfdc074b0a9a113a59bcebee8869d07 100644 (file)
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -54,6 +54,15 @@ remotes/git-svn.
 See '<<fetch-args,Additional Fetch Arguments>>' if you are interested in
 manually joining branches on commit.
 
+'dcommit'::
+       Commit all diffs from the current HEAD directly to the SVN
+       repository, and then rebase or reset (depending on whether or
+       not there is a diff between SVN and HEAD).  It is recommended
+       that you run git-svn fetch and rebase (not pull) your commits
+       against the latest changes in the SVN repository.
+       This is advantageous over 'commit' (below) because it produces
+       cleaner, more linear history.
+
 'commit'::
        Commit specified commit or tree objects to SVN.  This relies on
        your imported fetch data being up-to-date.  This makes
@@ -157,6 +166,24 @@ after the authors-file is modified should continue operation.
 
 repo-config key: svn.authors-file
 
+-m::
+--merge::
+-s<strategy>::
+--strategy=<strategy>::
+
+These are only used with the 'dcommit' command.
+
+Passed directly to git-rebase when using 'dcommit' if a
+'git-reset' cannot be used (see dcommit).
+
+-n::
+--dry-run::
+
+This is only used with the 'dcommit' command.
+
+Print out the series of git arguments that would show
+which diffs would be committed to SVN.
+
 --
 
 ADVANCED OPTIONS
@@ -217,6 +244,18 @@ doing.
 
 repo-config key: svn.noignoreexternals
 
+--ignore-nodate::
+Only used with the 'fetch' command.
+
+By default git-svn will crash if it tries to import a revision
+from SVN which has '(no date)' listed as the date of the revision.
+This is repository corruption on SVN's part, plain and simple.
+But sometimes you really need those revisions anyway.
+
+If supplied git-svn will convert '(no date)' entries to the UNIX
+epoch (midnight on Jan. 1, 1970).  Yes, that's probably very wrong.
+SVN was very wrong.
+
 --
 
 Basic Examples
@@ -235,12 +274,26 @@ Tracking and contributing to an Subversion managed-project:
        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 remotes/git-svn..my-branch
-# Something is committed to SVN, pull the latest into your branch:
-       git-svn fetch && git pull . remotes/git-svn
+# Something is committed to SVN, rebase the latest into your branch:
+       git-svn fetch && git rebase remotes/git-svn
 # Append svn:ignore settings to the default git exclude file:
        git-svn show-ignore >> .git/info/exclude
 ------------------------------------------------------------------------
 
+REBASE VS. PULL
+---------------
+
+Originally, git-svn recommended that the remotes/git-svn branch be
+pulled from.  This is because the author favored 'git-svn commit B'
+to commit a single head rather than the 'git-svn commit A..B' notation
+to commit multiple commits.
+
+If you use 'git-svn commit A..B' to commit several diffs and you do not
+have the latest remotes/git-svn merged into my-branch, you should use
+'git rebase' to update your work branch instead of 'git pull'.  'pull'
+can cause non-linear history to be flattened when committing into SVN,
+which can lead to merge commits reversing previous commits in SVN.
+
 DESIGN PHILOSOPHY
 -----------------
 Merge tracking in Subversion is lacking and doing branched development
@@ -339,6 +392,10 @@ 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.
 
+SEE ALSO
+--------
+gitlink:git-rebase[1]
+
 Author
 ------
 Written by Eric Wong <normalperson@yhbt.net>.