= cvsconvert(1) =
:doctype: manpage

== NAME ==
cvsconvert - perform a Git conversion and test against the CVS original

== SYNOPSIS ==
*cvsconvert* [-v] [-n] [-p] [-A 'authormap'] [repo | repo/module]

== DESCRIPTION ==
cvsconvert performs a conversion of a CVS repository to Git and
checks the tree contents at all branch tips and tags to verify that
the histories are the same.

Barring the known limitations in in the underlying cvs-fast-export(1)
engine, the conversion will be correct but not optimal.  You will
probably want to edit the resulting Git repository with reposurgeon(1)
to remove junk tags, lift references, Gitify change comments, and
perform various other cleanup tasks as described in
http://www.catb.org/~esr/reposurgeon/repository-editing.html[Repository
Editing and Conversion With Reposurgeon].

(An exception: synthetic gitspace branches named *-UNNAMED-BRANCH
created to collect homeless CVS commits are not checked. You will
see a warning when one of these is skipped.)

The single argument must be a path to a directory containing a a CVS
repository or module. If it is a CVS top-level directory and there is 
only one module beneath the module need not be specified. 

The Git conversion is left in a directory named after the repo
argument, with a suffix of "-git".

Normal behavior is for the program to report on each branch and tag,
saying "trees match as expected". There are two kinds of problem report:

*"file manifests don't match"*: Indicates that the CVS and Git
versions of this revision in the history contain some filenames that
don't pair up with each other. (Git and CVS ignore-pattern files are
ignored and will not trigger this message.)  When this message occurs,
files in common are still checked for equality.   

*"%s and %s are different"*: Two corresponding CVS and Git files do 
not compare equal. A diff listing will follow.

== Troubleshooting ==

There are two kinds of non-serious conversion glitches: file content
mismatches due to keyword fields in masters, and files deleted
in CVS that occur only in the gitspace manifests associated with tags.

You can spot content mismatches due to keyword expansion easily.  They
will produce single-line diffs of lines containing dollar signs
surrounding keyword text.  Because binary files can be corrupted by
keyword expansion, cvs-fast-export behaves like cvs -kb mode and does
no keyword expansion of its own.

Manifest mismatches on tags are most likely to occur on
files which were deleted in CVS but persist under later tags in the
Git conversion.  You can bet this is what's going on if, when you
search for the pathname in the CVS repository, you find it
in an Attic directory.

These spurious reports happens because CVS does not always retain
enough information to track deletions reliably and is somewhat flaky
in its handling of "dead"-state revisions. To make your CVS and git
repos match perfectly, you may need to add delete fileops to the
conversion - or, more likely, move existing ones back along their
branches to commits that predate the gitspace tag - using
reposurgeon(1).

Manifest mismatches in the other direction (present in CVS, absent
in gitspace) should never occur.  If one does, submit a bug report.

Any other kind of content or manifest match - but especially any on
the master branch - is bad news and indicates either a severe
repository malformation or a bug in cvs-fast-export (or possibly
both). Any such situation should be reported as a bug.

Conversion bugs are disproportionately likely to occur on older,
branches or tags from before CVS had reliable commitids. Often the
most efficient remedy is simply to delete junk branches and tags;
reposurgeon(1) makes this easy to do.  

If you need to file a bug, please visit the project website to
http://www.catb.org/~esr/cvs-fast-export/reporting-bugs.html]learn
about the bug-reporting procedure]. There are specific things you can
do when preparing the report to make a rapid resolution of the problem
more likely.

== OPTIONS ==
-p::
    Enable progress reports from cvs-fast-export as it runs.

-k::
    Pass a keyword-expansion specification to cvs-fast-export(1) and cvs(1).

-n::
    Test only, do not keep the Git conversion after emitting diagnostics.

-v::
    Verbose.  Show subcommands as they are being executed, and various
    debugging messages.

-q::
    Tell cvs-fast-export to run quietly.
    
-A 'authormap'::
    Pass cvs-fast-export an author map; see its man page for the format.

== LIMITATIONS ==

Warning: As of September 2016, stock CVS is known buggy in ways which
may affect checking the correctness of conversions. For best results,
use a CVS version with the MirOS patches.  These are carried by Debian
Linux and derivatives; you can check by Looking for "MirDebian" in the
output of cvs --version.

This program does not cope gracefully if CVS tagnames that are not
legal for Git had to be sanitized during conversion.

Because of the way this program works around CVS's requirement for a
CVSROOT directory, it will require directory write permission on the
repository directory in that case - otherwise it will abort after a
CVS message "failed to obtain dir lock in repository". The repository
contents are not modified.

The program needs the cvs -R option to access the repository
read-only.  It will therefore fail with versions of GNU CVS older
than 1.12.1 (2005) that do not have this option.

== REPORTING BUGS ==
Report bugs to Eric S. Raymond <esr@thyrsus.com>.  The project page is
at http://catb.org/~esr/cvs-fast-export

== SEE ALSO ==
rcs(1), cvs(1), cvs-fast-export(1), reposurgeon(1).
