NAME

       repotool - operate on a CVS, SVN, git, bzr, hg, or darcs repository in a uniform way

SYNOPSIS

       repotool 'command' [-d | -q | -v] [args...]

DESCRIPTION

       repotool is a wrapper around repository operations that differ by version-control system.
       It is little use by itself, existing mainly to generate and simplify a conversion makefile
       usable with reposurgeon(1).

       Not all actions are supported on all systems. You will get an error message and a return
       value of 1 when attempting an unsupported action.

       With the -v option, report the commands executed just before they are run. With the -q
       option, only fatal errors are printed instead of non-fatal gripes. The -q and -v options
       also disable each other and only the last one will take effect.

       With the -d option, change to a specified directory before performing whatever operation
       was selected. If the directory doesn’t exist or can’t be searched into, that’s a fatal
       error.

       The following subcommands are available:

       initialize
           The "initialize" option takes a project name (and, optionally, following source and
           target VCS types) and generates a Makefile that will sequence various steps of a
           repository conversion. It also generates stub lift and options files. This is meant to
           be run in an empty work directory, the tool will refuse to step on any of these files
           that already exist. Afterwards, you will need to set some variables in the Makefile;
           read its header comment.

       export
           The 'export' action, run from within a repository directory, dumps a copy of a CVS,
           Subversion, git, bzr, hg, or darcs repository to a flat history file readable by
           reposurgeon. The format is usually a git-fast-import stream, except that Subversion
           repositories export as Subversion dump files; the point is to be a lossless
           representation, or as close to one as possible.

       mirror
           The 'mirror' action makes or updates a local mirror of a Subversion, CVS, git, or hg
           repo. It requires a single argument, either a repository URL or the name of a local
           mirror directory created by a previous run. The first form creates a local mirror of
           the repository in a directory named after the last segment of the URL, with the suffix
           "-mirror" (the local mirror name can be overridden by an optional second argument).
           The second form updates the local mirror, doing an incremental fetch; just give the
           mirror directory name. If the environment variables RUSERNAME and RPASSWORD are set,
           they are used as login/password credentials for Subversion mirroring.

           Subversion URLs are as specified in the public documentation for Subversion. CVS URLs
           must specify a host and repository path, followed by a '#', followed by a module name.
           URLs for git and hg should be in the form normally used for clone commands.
           Alternatively, a repository URL may be a "file://" URL, in which case the repository
           type is autodetected from the contents of the indicated directory. Note: A Subversion
           file URL has three slashes after the "file:" prefix!

           The mirror command can also be passed an rsync URL. This will usually be faster than
           mirroring through an equivalent Subversion URL.

       branches
           The 'branches' option, run from within a repository directory , returns a list of the
           repository’s branch names.

       checkout
           The 'checkout' option checks out a working copy of the repository. It must be called
           from within the repository. It takes one required argument - the checkout directory
           location.

       compare
           The 'compare' action takes two repository directories. It may optionally take a
           tag-branch-revision spec as for the checkout option. You can also pass two revisions
           separated by a colon to the -r option, to have the first one checked out in the first
           repository and the second one in the second repository. That permits one to compare
           two different revisions, or the same revision referenced differently in two VCS. You
           can leave one of the two revisions empty, then the -r option will not be passed to the
           corresponding repository checkout. This is useful to compare a git tag or branch to
           the corresponding tag or branch in SVN as seen at a particular revision (specifying
           both a branch and revision makes sense in SVN, but not in git). The selected versions
           are compared with diff -r, with noise due to SCCS/RCS/CVS keyword expansion ignored.
           File permissions well as content are checked, any mismatches will be shown after the
           diff listing.

       compare-tags
           The 'compare-tags' action takes two repository directories, extracts a list of tags
           from the first, then compares the repository contents at each tag in the list,
           generating a compare report for each. Takes compare options. Additionally the -e
           option sets exclude patterns for tag names that should be ignored.

       compare-branches
           The 'compare-branches' action takes two repository directories, extracts a list of
           branches common to both, then compares the repository contents at each branch in the
           list, generating a compare report for each. Takes compare options. Additionally the -e
           option sets exclude patterns for branch names that should be ignored.

       compare-all
           The 'compare-all' action takes two repository directories, and runs all three above
           compare actions on them. Even if the same name is a tag in one repository and a branch
           in the other, it will compare them against each other. Not distinguishing them is
           useful as CVS tags that are not applied to every file in the repository may get
           converted to branches. Takes compare options. Additionally the -e option sets exclude
           patterns for tag and branch names that should be ignored.

       version
           The "version" command reports the version level of the software.

       help
           The "help" command displays a summary of commands and options. With a following
           argument that is a command name, display detailed help for that command.

       There is one special checkout option:

       -o
           Pass the following option through to the underlying checkout command. Can be used, for
           example, to pass in Subversion’s --ignore-externals option.

       The compare operation accepts the following options:

       -n
           Passed to the individual checkout commands which means that in cases where it makes
           sense the complete repository will be checked out flatly, treating branch and tag
           namespaces as simple directories.

       -a
           Use an empty directory as the checkout if the asked branch or tag cannot be found,
           instead of erroring out without any comparison. This is useful when if the other
           repository uses empty content for deleted refs.

       -u
           Emit unified diff (default).

       -c
           Emit context diff.

       -q
           Suppress nonfatal errors and progress spinners. The progress sinner is also suppressed
           when output is redirected to a file or pipe.

       -s
           List matching files.

       -i
           Perform comparison of normally ignored dot directories

ENVIRONMENT VARIABLES

       This program uses the $TMPDIR environment variable, defaulting to '/tmp' if it is not set,
       to set where checkouts for repository comparisons are done.

RETURN VALUES

       1 on invalid arguments or if a command called by the script failed, 0 otherwise. A return
       value of 0 on a compare operation does not necessarily indicate a clean comparison; only
       empty output does that.

BUGS

       CVS repositories have an unnamed default branch. This is not listed by "repotool
       branches"; if there are no named branches the output is empty.

       When a Subversion file is part of a mismatch, the displayed filename is missing its
       trunk/tag/branch location, which must be inferred from the way the comparison is invoked.

       Tag comparisons with git will not cope well with a branch name containing the string
       "detached".

       Due to extreme slowness of the Subversion checkout operation, the compare head, tag, and
       branch modes assume that if one of the directories is a Subversion checkout you have done
       a full checkout of HEAD before calling this tool; thus no svn update operation is required
       unless you give an -r option. Spurious errors will be reported if the directory is not a
       full checkout of HEAD. To avoid this optimization and force updating, do "-r HEAD".

REQUIREMENTS

       The export action is a wrapper around either native export facilities or the following
       engines: cvs-fast-export(1) (for CVS), svnadmin(1) (for SVN), reposurgeon itself (for hg).
       You must have the appropriate engine in your $PATH for whatever kind of repository you are
       streaming.

            [[see_also]]
           == SEE ALSO ==

       reposurgeon(1).

AUTHOR

       Eric S. Raymond esr@thyrsus.com. This tool is distributed with reposurgeon; see the
       project <http://www.catb.org/~esr/reposurgeon> page" .

                                            2024-01-29                                REPOTOOL(1)