Ubuntu Manpage: cvsconvert - perform a Git conversion and test against the CVS original

Provided by: cvs-fast-export_1.35-1_amd64

NAME

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

SYNOPSIS

       cvsconvert [-v] [-n] [-p] [-k expandspec] [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.

       (An exception: synthetic gitspace branches enamed *-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 expanded 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, by default cvs-fast-export behaves like cvs -kb mode and does no keyword expansion of its own.
Thus, you should never see such mismatches unless you have passed in a -k option.

However, you might want to pass in -k k if (a) you believe the CVS masters might contain expanded keyword
fields but don’t want to clean them up by hand, and (b) you are confident your repository contains no
binary files that might false-match an RCS/CVS keyword. If you are wrong about assumption (b) you will
receive warning messages about content mismatches in the binary files.

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 use 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 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.

LIMITATIONS

       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