Re: [PATCH] Add SVN->Git conversion example to documentation

[Junio C Hamano <junio@pobox.com>]

Heikki Orsila <heikki.orsila@iki.fi> writes:

> Signed-off-by: Heikki Orsila <heikki.orsila@iki.fi>
> ---
> This is the third round. Added some commands to clean up the repository, 
> and set fetch heads. Thanks to Miklos Vajna for feedback.
>
>  Documentation/git-svn.txt |   41 ++++++++++++++++++++++++++++++++++++++---
>  1 files changed, 38 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
> index f4cbd2f..26e00c5 100644
> --- a/Documentation/git-svn.txt
> +++ b/Documentation/git-svn.txt
> @@ -11,9 +11,12 @@ 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 projects with Git tools,
> +but commit changes to a Subversion repository. It can also be used to

That is correct but doesn't the above give a false impression that commits
are only made on subversion side and never on git side?

> +convert a Subversion repository to a Git repository. It should not
> +be confused with linkgit:git-svnimport[1], which does Subversion to
> +Git conversion, but not the other direction.

We do not ship nor document svnimport anymore and linkgit: there is
actively wrong.  People seem to be confused with ancient documents still
floating on the Web that talk about svnimport, and I think it is a good
idea to try to clear the confusion here, but perhaps...

	... with the deprecated `git-svnimport`, which was used for
	one-way conversion from Subversion to git.

> @@ -520,6 +523,38 @@ 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 removes "git-svn-id:" comments from the log.
> +-A option is used to convert SVN pseudonyms to real names

Anything that user usually would type on the command line it is preferred
to typeset with `quoted like this`, so "`--no-metadata`" and "`-A` option".

It is not `--no-metadata` "removes".  git-svn adds cruft because it wants
to use it for bidi operation, but --no-metadata prevents it from doing
so.