[PATCH] Add SVN->Git conversion example to documentation, and cleanup the doc

[PATCH] Add SVN->Git conversion example to documentation, and cleanup the doc

[Heikki Orsila]

Signed-off-by: Heikki Orsila <heikki.orsila@iki.fi>
---
This is the fourth round of the patch. Changes to earlier attempts:

* Explain git<>svn process better (Junio C Hamano)

* Don't mention git-svnimport unnecessarily. And where mentioned, 
  mark it as deprecated. (Karl Hasselström, Junio C Hamano)

* Remove unnecessary words from description

* Rename foo.git -> foo (Miklos Vajna)

* Remove refs/remotes/git-svn (Miklos Vajna)

* Don't set unnecessary fetch sources

* Use proper syntax for marking command line options in the text.
  Use "`--no-metadata`" instead of "--no-metadata". (Junio C Hamano)

* Improve explanation of "`--no-metadata`"

* This patch explains how to do one step transition to Git repository.
  Further updates from the SVN repo are not possible. A later patch may
  explain the process of incremental updates, but it doesn't really
  address the issue of moving from SVN to Git as Git should be
  self-sufficient. (Miklos Vajna)

 Documentation/git-svn.txt |   56 +++++++++++++++++++++++++++++++++++++--------
 1 files changed, 46 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 97bed54..551f1df 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -11,15 +11,15 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-git-svn is a simple conduit for changesets between Subversion and git.
-It is not to be confused with linkgit:git-svnimport[1], which is
-read-only.
+git-svn is a simple bidirectional conduit for changesets between
+Subversion and git. It is used to develop SVN hosted projects with Git tools.
+Changes are committed to a Git repository as would be normally done with
+Git, but the tool converts these commits later to SVN commits.
+It can also be used to convert a Subversion repository to a Git repository.
 
-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.
+git-svn was designed for developers who want
+bidirectional flow of changesets between multiple branches in Subversion
+and an arbitrary number of branches in git. 
 
 git-svn is especially useful when it comes to tracking repositories
 not organized in the way Subversion developers recommend (trunk,
@@ -219,7 +219,7 @@ Any other arguments are passed directly to `git log'
 'commit-diff'::
 	Commits the diff of two tree-ish arguments from the
 	command-line.  This command is intended for interoperability with
-	git-svnimport and does not rely on being inside an git-svn
+	git-svnimport (deprecated) and does not rely on being inside an git-svn
 	init-ed repository.  This command takes three arguments, (a) the
 	original tree to diff against, (b) the new tree result, (c) the
 	URL of the target Subversion repository.  The final argument
@@ -317,7 +317,7 @@ config key: svn.findcopiesharder
 -A<filename>::
 --authors-file=<filename>::
 
-Syntax is compatible with the files used by git-svnimport and
+Syntax is compatible with the files used by git-svnimport (deprecated) and
 git-cvsimport:
 
 ------------------------------------------------------------------------
@@ -521,6 +521,42 @@ have each person clone that repository with 'git clone':
 	git-svn rebase
 ------------------------------------------------------------------------
 
+CONVERTING A SUBVERSION REPOSITORY TO A GIT REPOSITORY
+------------------------------------------------------
+
+When converting a Subversion repository to a Git repository
+"`--no-metadata`" prevents git-svn from adding "git-svn-id:" comments to
+the log. "`-A`" option is used to convert SVN pseudonyms to real names
+and email addresses. The whole repository, or a part of it can be
+converted. Two examples below show how to convert the whole repo
+with all branches, or only the SVN trunk. Note, this way it is
+impossible to update Git repository incrementally from the SVN repository.
+This is a one-step, one-way conversion.
+
+------------------------------------------------------------------------
+# Convert all branches of an SVN repository to a Git repository:
+
+	git svn clone --no-metadata -A authors.txt SVN_URL foo
+
+# Convert only the trunk of an SVN repository to a Git repository:
+
+	git svn clone --no-metadata -A authors.txt SVN_URL/trunk foo
+------------------------------------------------------------------------
+Next, the new repository should be verified to match what was
+expected. Go through the repository and logs to do that.
+Also, there may have been typos in the author file. It is crucial to
+get authors correctly in the conversion step, because it is very
+awkward and inconvenient to do it later (with rewrite).
+The last step is to remove the svn data from the repository,
+and repack the repository.
+------------------------------------------------------------------------
+	cd foo/.git
+	rm -rf svn
+	rm -f refs/remotes/git-svn
+	git config --remove-section svn-remote.svn
+	git gc
+------------------------------------------------------------------------
+
 REBASE VS. PULL/MERGE
 ---------------------
 
-- 
1.5.5.1.1.ga5e5c