[PATCH 0/3] update git cvs import documentation

[PATCH 0/3] update git cvs import documentation

[Jeff King]

I dreamed a dream that I would never have to think about git-cvsimport
again. And yet. Somebody reported[1] that the link to cvsps in
gitcvs-migration is broken. While fixing it, I noticed a few other
out-of-date items. I haven't used any of these tools myself in years,
but hopefully these changes are minimal no-brainers.

  [1/3]: docs/cvsimport: prefer cvs-fast-export to parsecvs
  [2/3]: docs/cvs-migration: update link to cvsps homepage
  [3/3]: docs/cvs-migration: mention cvsimport caveats

-Peff

[1] https://github.com/git/git-scm.com/issues/851

[PATCH 1/3] docs/cvsimport: prefer cvs-fast-export to parsecvs

[Jeff King]

parsecvs maintenance was taken over by ESR, and the name
changed to cvs-fast-export as it learned to support that
output format. Let's point to cvs-fast-export, as it should
have additional bug-fixes and be more convenient to use.

Signed-off-by: Jeff King <peff@peff.net>
---
No opinion on how this compares to cvs2git these days, so I made the
minimal change here. Anyone may feel free to debate it, but kindly
remove me from the Cc of any flamewars. :)

 Documentation/git-cvsimport.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt
index 41207a2..de1ebed 100644
--- a/Documentation/git-cvsimport.txt
+++ b/Documentation/git-cvsimport.txt
@@ -22,7 +22,7 @@ DESCRIPTION
 deprecated; it does not work with cvsps version 3 and later.  If you are
 performing a one-shot import of a CVS repository consider using
 http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or
-https://github.com/BartMassey/parsecvs[parsecvs].
+http://www.catb.org/esr/cvs-fast-export/[cvs-fast-export].
 
 Imports a CVS repository into Git. It will either create a new
 repository, or incrementally import into an existing one.
-- 
2.10.0.482.gae5a597

[PATCH 2/3] docs/cvs-migration: update link to cvsps homepage

[Jeff King]

The old page gives a 404 now. Searching for "cvsps" via
Google returns a GitHub project page as the top hit.

Reported-by: Dan Pritts
Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/gitcvs-migration.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt
index b06e852..faee5c2 100644
--- a/Documentation/gitcvs-migration.txt
+++ b/Documentation/gitcvs-migration.txt
@@ -117,7 +117,7 @@ Importing a CVS archive
 -----------------------
 
 First, install version 2.1 or higher of cvsps from
-http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make
+https://github.com/andreyvit/cvsps[https://github.com/andreyvit/cvsps] and make
 sure it is in your path.  Then cd to a checked out CVS working directory
 of the project you are interested in and run linkgit:git-cvsimport[1]:
 
-- 
2.10.0.482.gae5a597

[PATCH 3/3] docs/cvs-migration: mention cvsimport caveats

[Jeff King]

Back when this guide was written, cvsimport was the only
game in town. These days it is probably not the best option.
Rather than go into details, let's point people to the note
at the top of cvsimport which gives other options.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/gitcvs-migration.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt
index faee5c2..4c6143c 100644
--- a/Documentation/gitcvs-migration.txt
+++ b/Documentation/gitcvs-migration.txt
@@ -116,6 +116,10 @@ they create are writable and searchable by other group members.
 Importing a CVS archive
 -----------------------
 
+NOTE: These instructions use the `git-cvsimport` script which ships with
+git, but other importers may provide better results. See the note in
+linkgit:git-cvsimport[1] for other options.
+
 First, install version 2.1 or higher of cvsps from
 https://github.com/andreyvit/cvsps[https://github.com/andreyvit/cvsps] and make
 sure it is in your path.  Then cd to a checked out CVS working directory
-- 
2.10.0.482.gae5a597

Re: [PATCH 3/3] docs/cvs-migration: mention cvsimport caveats

[Eric S. Raymond]

Jeff King <peff@peff.net>:
> Back when this guide was written, cvsimport was the only
> game in town. These days it is probably not the best option.

It is absolutely not.  As I have tried to point out here before, it
is *severely* broken in its processing of branchy CVS repositories.

Nobody wanted to hear that, but it's still true. Recommending it
is irresponsible.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [PATCH 3/3] docs/cvs-migration: mention cvsimport caveats

[Jeff King]

On Thu, Sep 22, 2016 at 09:15:26AM -0400, Eric S. Raymond wrote:

> Jeff King <peff@peff.net>:
> > Back when this guide was written, cvsimport was the only
> > game in town. These days it is probably not the best option.
> 
> It is absolutely not.  As I have tried to point out here before, it
> is *severely* broken in its processing of branchy CVS repositories.
> 
> Nobody wanted to hear that, but it's still true. Recommending it
> is irresponsible.

I think your points came across, and that is why we have the big warning
in git-cvsimport in the first place. This is really just adding a
pointer to that warning from another relevant location (that frankly, I
didn't even know existed until fixing a nearby problem).

I _do_ think cvsimport, buggy as it may be, may still have some
potential value over other solutions (if you have a simple history, and
it is easier to install or run than the alternatives). But I converted
all of my CVS history to git over ten years ago and have never looked
back. I really don't know if that is the case or not.

So personally I have no objection if somebody wants to rewrite the
gitcvs-migration page to discuss the other options more thoroughly, or
warn more clearly about cvsimport's flaws. These patches were just
"Jeez, we are not even warning people _at all_, so at the minimum we
should do so". I am not qualified to write on the current state of
the art in CVS importing.

-Peff

Re: [PATCH 3/3] docs/cvs-migration: mention cvsimport caveats

[Eric S. Raymond]

Jeff King <peff@peff.net>:
>               I am not qualified to write on the current state of
> the art in CVS importing.

I *am* qualified; cvs-fast-export has had a lot of work put into it by
myself and others over the last five years.  Nobody else is really
working this problem anymore, not much else than cvs2git is even left
standing at this point. Most other attempts on the problem have
stalled or flamed out, and were never very robust in dealing with
repository malformations to begin with.

cvs2git can probably still almost match cvs-fast-export in ability to handle
pathological cases, but is painfully slow by comparison.  (Part of that is
implementation in Python vs. C.)

cvs-fast-export has been successfully performance-tuned for very large
repositories, such as the entirety of NetBSD, and is orders of
magnitude faster than it used to be. (I parallelized the parsing
of RCS masters with a re-entrant Bison instance running per thread;
this makes a huge difference on large repositories, for which that
stage dominates running time.) Its ability to recover sense from
repository malformations was already pretty good five years ago
and is probably unmatched now.  It does .cvsignore conversion.

cvs-fast-export also now has a really good test suite collecting all
kinds of weird CVS deformations from the field, and a wrapper that can
both do a conversion and check for correctness at every tag as well as
the tip revision.

By contrast, the wrapper/cvsps combination git ships continues to be
disgracefully bad and should be scrapped - remember that I maintained
cvsps for a while and tried to EOL it because its branch-resolution
algorithms are unsound.  I have a replacement wrapper ready any time
the git maintainer decides to stop shipping broken, dangerous code.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [PATCH 3/3] docs/cvs-migration: mention cvsimport caveats

[Jeff King]

On Tue, Sep 27, 2016 at 08:11:08PM -0400, Eric S. Raymond wrote:

> Jeff King <peff@peff.net>:
> >               I am not qualified to write on the current state of
> > the art in CVS importing.
> 
> I *am* qualified; cvs-fast-export has had a lot of work put into it by
> myself and others over the last five years.

I, for one, would be fine if you wanted to send a patch updating
Documentation/gitcvs-migration.txt to describe cvs-fast-export rather
than cvsimport. I think it would probably even be fine if it mostly just
pointed to an existing guide and said "use this".

-Peff

Re: [PATCH 3/3] docs/cvs-migration: mention cvsimport caveats

[Junio C Hamano]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Jeff King <peff@peff.net>:
>>               I am not qualified to write on the current state of
>> the art in CVS importing.
>
> I *am* qualified; cvs-fast-export has had a lot of work put into it by
> myself and others over the last five years.  Nobody else is really
> working this problem anymore, not much else than cvs2git is even left
> standing at this point.

It sounds like you, as a better qualified person, would be in the
best position to send an update to the documentation to tell people
not to use older and unmaintained ones and guides them instead to a
newer and better tool.

    ... ah, I notice that peff said the same already.

I'd be fine with reviewing and applying such a patch.

Thanks.