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

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

[Keshav Kini]

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>
---
 Documentation/git-svn.txt | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 4dd3bcb..040117a 100644
--- 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.
 
 --localtime;;
 	Store Git commit times in the local timezone instead of UTC.  This
@@ -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
 be able to rebuild them.
 +
 The 'git svn log' command will not work on repositories using
-- 
1.8.3.2

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

[Jonathan Nieder]

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

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

[Eric Wong]

Jonathan Nieder <jrnieder@gmail.com> wrote:
> Keshav Kini wrote:
> > +	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

I agree with Jonathan's suggestions.

Keshav: can you please resend with Jonathan's suggestions?
Thanks both.

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

[Keshav Kini]

Jonathan Nieder <jrnieder@gmail.com> writes:
> 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).

Note that only the first two asterisks are escaped in my patch. For some
reason, escaping all three causes a literal '\' to appear in asciidoc's
output...

I changed the wording of your first paragraph a bit according to what I
thought it meant. Does it still convey what you wanted to convey, and is
it still correct?

	Mapping between Subversion revision numbers and Git commit
	names.  In a repository where the noMetadata option is not set,
	this can be rebuilt from the git-svn-id: lines that are at the
	end of every commit (see the 'svn.noMetadata' section above for
	details).

Also, I'm having a bit of trouble trying to get a definition to start
with a '.' character in AsciiDoc.  Escaping the '.' produces a
definition block, but with a literal '\' before the '.'.  If I don't
escape the '.', asciidoc thinks it's a section heading or something. Is
asciidoc just incapable of doing this, or am I missing something?

-Keshav

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

[Jonathan Nieder]

Keshav Kini wrote:

> I changed the wording of your first paragraph a bit according to what I
> thought it meant. Does it still convey what you wanted to convey, and is
> it still correct?
>
>         Mapping between Subversion revision numbers and Git commit
>         names.  In a repository where the noMetadata option is not set,
>         this can be rebuilt from the git-svn-id: lines that are at the
>         end of every commit (see the 'svn.noMetadata' section above for
>         details).

Sounds good.

> Also, I'm having a bit of trouble trying to get a definition to start
> with a '.' character in AsciiDoc.  Escaping the '.' produces a
> definition block, but with a literal '\' before the '.'.  If I don't
> escape the '.', asciidoc thinks it's a section heading or something. Is
> asciidoc just incapable of doing this, or am I missing something?

Oh.  Yeah, this can be a pain.  Quoting the filename with `backticks`
might work.  Writing $GIT_DIR instead of .git might be simpler (see
v1.5.3.2~18 "Documentation/git-config.txt: AsciiDoc tweak to avoid
leading dot", 2007-09-14).

Thanks,
Jonathan

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

[Keshav Kini]

Jonathan Nieder <jrnieder@gmail.com> writes:
> Keshav Kini wrote:
>
>> I changed the wording of your first paragraph a bit according to what I
>> thought it meant. Does it still convey what you wanted to convey, and is
>> it still correct?
>>
>>         Mapping between Subversion revision numbers and Git commit
>>         names.  In a repository where the noMetadata option is not set,
>>         this can be rebuilt from the git-svn-id: lines that are at the
>>         end of every commit (see the 'svn.noMetadata' section above for
>>         details).
>
> Sounds good.
>
>> Also, I'm having a bit of trouble trying to get a definition to start
>> with a '.' character in AsciiDoc.  Escaping the '.' produces a
>> definition block, but with a literal '\' before the '.'.  If I don't
>> escape the '.', asciidoc thinks it's a section heading or something. Is
>> asciidoc just incapable of doing this, or am I missing something?
>
> Oh.  Yeah, this can be a pain.  Quoting the filename with `backticks`
> might work.  Writing $GIT_DIR instead of .git might be simpler (see
> v1.5.3.2~18 "Documentation/git-config.txt: AsciiDoc tweak to avoid
> leading dot", 2007-09-14).

Good point.  Actually it seems to me that writing $GIT_DIR is in fact
more correct, since $GIT_DIR need not be ".git" at all.  So I'll just
use that.  Reroll coming up in a bit.

-Keshav

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

[Keshav Kini]

Jonathan Nieder <jrnieder@gmail.com> writes:
>> @@ -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. ;-)

May I also roll into said commit a couple of replacements of ".git" with
"$GIT_DIR" in the same file, or other such minor touchups?

-Keshav

[PATCH v2 0/4] git-svn.txt: miscellaneous changes

[Keshav Kini]

I'm not sure if this was the best way to split my changes into commits.
Please let me know if it wasn't.

Keshav Kini (4):
  git-svn.txt: fix AsciiDoc formatting error
  git-svn.txt: reword description of gc command
  git-svn.txt: replace .git with $GIT_DIR
  git-svn.txt: elaborate on rev_map files

 Documentation/git-svn.txt | 46 +++++++++++++++++++++++++++++++++-------------
 1 file changed, 33 insertions(+), 13 deletions(-)

-- 
1.8.3.2

[PATCH v2 1/4] git-svn.txt: fix AsciiDoc formatting error

[Keshav Kini]

As asterisks are used to indicate bold text in AsciiDoc, shell glob
expressions must be escaped appropriately.

Signed-off-by: Keshav Kini <keshav.kini@gmail.com>
---
 Documentation/git-svn.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 4dd3bcb..239c33c 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -684,7 +684,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
 be able to rebuild them.
 +
 The 'git svn log' command will not work on repositories using
-- 
1.8.3.2

[PATCH v2 2/4] git-svn.txt: reword description of gc command

[Keshav Kini]

It's redundant to say that $GIT_DIR/svn/<refname>/unhandled.log or
$GIT_DIR/svn/<refname>/index is in .git/svn when $GIT_DIR is '.git', and
is wrong when $GIT_DIR is not '.git'

Also, a '/' was missing from the pathname $GIT_DIR/svn/<refname>/index .

Signed-off-by: Keshav Kini <keshav.kini@gmail.com>
---
 Documentation/git-svn.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 239c33c..62ec727 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -435,8 +435,8 @@ Any other arguments are passed directly to 'git log'
 	specific revision.
 
 'gc'::
-	Compress $GIT_DIR/svn/<refname>/unhandled.log files in .git/svn
-	and remove $GIT_DIR/svn/<refname>index files in .git/svn.
+	Compress $GIT_DIR/svn/<refname>/unhandled.log files and remove
+	$GIT_DIR/svn/<refname>/index files.
 
 'reset'::
 	Undoes the effects of 'fetch' back to the specified revision.
-- 
1.8.3.2

[PATCH v2 3/4] git-svn.txt: replace .git with $GIT_DIR

[Keshav Kini]

As $GIT_DIR may not equal '.git', it's usually more generally correct to
refer to files in $GIT_DIR rather than in .git .

This will also allow me to link some of the occurrences of '.git' in
git-svn.txt to a new reference target inside this file in an upcoming
commit, because in AsciiDoc definitions apparently can't start with
a '.' character.

Signed-off-by: Keshav Kini <keshav.kini@gmail.com>
---
 Documentation/git-svn.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 62ec727..3ddf545 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -104,8 +104,8 @@ 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.
+	$GIT_DIR/config file may be specified as an optional
+	command-line argument.
 
 --localtime;;
 	Store Git commit times in the local timezone instead of UTC.  This
@@ -684,7 +684,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_DIR/svn/\*\*/.rev_map.* files, 'git svn' will not
 be able to rebuild them.
 +
 The 'git svn log' command will not work on repositories using
@@ -977,8 +977,8 @@ When using multiple --branches or --tags, 'git svn' does not automatically
 handle name collisions (for example, if two branches from different paths have
 the same name, or if a branch and a tag have the same name).  In these cases,
 use 'init' to set up your Git repository then, before your first 'fetch', edit
-the .git/config file so that the branches and tags are associated with
-different name spaces.  For example:
+the $GIT_DIR/config file so that the branches and tags are associated
+with different name spaces.  For example:
 
 	branches = stable/*:refs/remotes/svn/stable/*
 	branches = debug/*:refs/remotes/svn/debug/*
@@ -1006,7 +1006,7 @@ CONFIGURATION
 -------------
 
 'git svn' stores [svn-remote] configuration information in the
-repository .git/config file.  It is similar the core Git
+repository $GIT_DIR/config file.  It is similar the core Git
 [remote] sections except 'fetch' keys do not accept glob
 arguments; but they are instead handled by the 'branches'
 and 'tags' keys.  Since some SVN repositories are oddly
@@ -1060,8 +1060,8 @@ $ git svn branch -d branches/server release-2-3-0
 
 Note that git-svn keeps track of the highest revision in which a branch
 or tag has appeared. If the subset of branches or tags is changed after
-fetching, then .git/svn/.metadata must be manually edited to remove (or
-reset) branches-maxRev and/or tags-maxRev as appropriate.
+fetching, then $GIT_DIR/svn/.metadata must be manually edited to remove
+(or reset) branches-maxRev and/or tags-maxRev as appropriate.
 
 SEE ALSO
 --------
-- 
1.8.3.2

[PATCH v2 4/4] git-svn.txt: elaborate on rev_map files

[Keshav Kini]

The man page for `git svn` describes a situation in which "'git svn'
will not be able to rebuild" your $GIT_DIR/svn/**/.rev_map* files, but
no mention is made of in what circumstances `git svn` *will* be able to
do so, how to get `git svn` to do so, or even what these files are.

This patch adds a FILES section to the man page with a description of
what $GIT_DIR/svn/**/.rev_map* files are and how they are (re)built, and
links to this description from various other parts of the man page.

Signed-off-by: Keshav Kini <keshav.kini@gmail.com>
---
 Documentation/git-svn.txt | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 3ddf545..5383496 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -106,6 +106,9 @@ COMMANDS
 	tracking.  The name of the [svn-remote "..."] section in the
 	$GIT_DIR/config file may be specified as an optional
 	command-line argument.
++
+This automatically updates the rev_map if needed (see
+'$GIT_DIR/svn/\*\*/.rev_map.*' in the FILES section below for details).
 
 --localtime;;
 	Store Git commit times in the local timezone instead of UTC.  This
@@ -201,6 +204,9 @@ accept.  However, '--fetch-all' only fetches from the current
 +
 Like 'git rebase'; this requires that the working tree be clean
 and have no uncommitted changes.
++
+This automatically updates the rev_map if needed (see
+'$GIT_DIR/svn/\*\*/.rev_map.*' in the FILES section below for details).
 
 -l;;
 --local;;
@@ -449,9 +455,10 @@ Any other arguments are passed directly to 'git log'
 	file cannot be ignored forever (with --ignore-paths) the only
 	way to repair the repo is to use 'reset'.
 +
-Only the rev_map and refs/remotes/git-svn are changed.  Follow 'reset'
-with a 'fetch' and then 'git reset' or 'git rebase' to move local
-branches onto the new tree.
+Only the rev_map and refs/remotes/git-svn are changed (see
+'$GIT_DIR/svn/\*\*/.rev_map.*' in the FILES section below for details).
+Follow 'reset' with a 'fetch' and then 'git reset' or 'git rebase' to
+move local branches onto the new tree.
 
 -r <n>;;
 --revision=<n>;;
@@ -684,7 +691,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_DIR/svn/\*\*/.rev_map.* files, 'git svn' will not
+if you lose your '$GIT_DIR/svn/\*\*/.rev_map.*' files, 'git svn' will not
 be able to rebuild them.
 +
 The 'git svn log' command will not work on repositories using
@@ -1063,6 +1070,19 @@ or tag has appeared. If the subset of branches or tags is changed after
 fetching, then $GIT_DIR/svn/.metadata must be manually edited to remove
 (or reset) branches-maxRev and/or tags-maxRev as appropriate.
 
+FILES
+-----
+$GIT_DIR/svn/\*\*/.rev_map.*::
+	Mapping between Subversion revision numbers and Git commit
+	names.  In a repository where the noMetadata option is not set,
+	this can be rebuilt from the git-svn-id: lines that are at the
+	end of every commit (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.
+
 SEE ALSO
 --------
 linkgit:git-rebase[1]
-- 
1.8.3.2

Re: [PATCH v2 0/4] git-svn.txt: miscellaneous changes

[Jonathan Nieder]

Keshav Kini wrote:

> Keshav Kini (4):
>   git-svn.txt: fix AsciiDoc formatting error
>   git-svn.txt: reword description of gc command
>   git-svn.txt: replace .git with $GIT_DIR
>   git-svn.txt: elaborate on rev_map files

Thanks.

Re: [PATCH v2 0/4] git-svn.txt: miscellaneous changes

[Eric Wong]

Keshav Kini <keshav.kini@gmail.com> wrote:
> I'm not sure if this was the best way to split my changes into commits.
> Please let me know if it wasn't.
> 
> Keshav Kini (4):
>   git-svn.txt: fix AsciiDoc formatting error
>   git-svn.txt: reword description of gc command
>   git-svn.txt: replace .git with $GIT_DIR
>   git-svn.txt: elaborate on rev_map files
> 
>  Documentation/git-svn.txt | 46 +++++++++++++++++++++++++++++++++-------------
>  1 file changed, 33 insertions(+), 13 deletions(-)

Good enough for me :)   Pushed to git-svn.git

The following changes since commit 128a96c98442524c7f2eeef4757b1e48445f24ce:

  Update draft release notes to 1.8.5 for the fifth batch of topics (2013-09-20 12:42:02 -0700)

are available in the git repository at:

  git://git.bogomips.org/git-svn.git master

for you to fetch changes up to 945b9c14ffd3e11c916ee2b2428a0b2be9645829:

  git-svn.txt: elaborate on rev_map files (2013-10-10 06:56:12 +0000)

----------------------------------------------------------------
Keshav Kini (4):
      git-svn.txt: fix AsciiDoc formatting error
      git-svn.txt: reword description of gc command
      git-svn.txt: replace .git with $GIT_DIR
      git-svn.txt: elaborate on rev_map files

Nicolas Vigier (1):
      git-svn: fix signed commit parsing

 Documentation/git-svn.txt | 46 +++++++++++++++++++++++++++++++++-------------
 git-svn.perl              |  2 +-
 2 files changed, 34 insertions(+), 14 deletions(-)