patch, 3 partsupdate git cvs import documentation

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

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(-)

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(-)

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(+)

Jeff King <peff@peff.net>:

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.

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

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

Jeff King <peff@peff.net>:

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.

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

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

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

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.