Re: [PATCH] git-svn.txt: mention how to rebuild rev_map files

[Jonathan Nieder <jrnieder@gmail.com>]

Hi,

Keshav Kini wrote:

> The man page for `git svn` describes a situation in which "'git svn'
> will not be able to rebuild" your .git/svn/**/.rev_map files, but no
> mention is made of in what circumstances `git svn` *will* be able to do
> so, or how to get `git svn` to do so.
>
> This patch adds some language to the description of the 'fetch' command
> to rectify this oversight, and also fixes an AsciiDoc escaping typo.
>
> Signed-off-by: Keshav Kini <keshav.kini@gmail.com>

Good idea.

[...]
> --- a/Documentation/git-svn.txt
> +++ b/Documentation/git-svn.txt
> @@ -103,9 +103,12 @@ COMMANDS
>  
>  'fetch'::
>  	Fetch unfetched revisions from the Subversion remote we are
> -	tracking.  The name of the [svn-remote "..."] section in the
> -	.git/config file may be specified as an optional command-line
> -	argument.
> +	tracking.  If necessary, rebuild the .git/svn/\*\*/.rev_map.*
> +	files, given the requisite information exists in commit
> +	messages (see the svn.noMetadata config option for more
> +	information).  The name of the [svn-remote "..."] section in
> +	the .git/config file may be specified as an optional
> +	command-line argument.

Taking a step back, the reader might wonder *why* he would want
to run "git svn fetch" to rebuilt these .rev_map.* files, and what
they are for.

Perhaps there should be a separate REVISION MAP section describing
this in more detail.  Something as simple as

	FILES
	-----
	.git/svn/\*\*/.rev_map.\*::
		Mapping between Subversion revision numbers and Git
		commit names.  Can be rebuilt using the git-svn-id:
		lines at the end of every commit as long as the
		noMetadata option is not set (see the 'svn.noMetadata'
		section above for details).
	+
	'git svn fetch' and 'git svn rebase' automatically update
	the rev_map if it is missing or not up to date.  'git svn
	reset' automatically rewinds it.

Then this reference in 'fetch' could just say something like

	...
	argument.
	+
 This automatically updates the rev_map if needed (see
 '.git/svn/\*\*/.rev_map.\*' in the FILES section below for
 details).

> @@ -684,7 +687,7 @@ svn-remote.<name>.noMetadata::
>  +
>  This option can only be used for one-shot imports as 'git svn'
>  will not be able to fetch again without metadata. Additionally,
> -if you lose your .git/svn/**/.rev_map.* files, 'git svn' will not
> +if you lose your .git/svn/\*\*/.rev_map.* files, 'git svn' will not

I don't mind seeing this fix snuck into the same commit, but a
separate commit that could be applied more quickly would be even
better. ;-)

Thanks and hope that helps,
Jonathan