Fossilisa   README

Description

Fossilisa is a program written in fish that extracts the content of Fossil or Git repositories, with some limitations, allowing to modify it in several ways (including combining several repositories) and then create a new Fossil repository from it.

How it works

The content of the source repository is extracted into a work directory. The content of every extracted commit or check-in (called "entry" here) is saved into a subdirectory named after the entry date, a label that identifies the source directory, the hash and the branch, separated by commas. Besides, a homonymous text file (with the ".comment.txt" extension) is created containing the corresponding entry comment.

Example of three entry subdirectories with their comment files:

2013-04-27T21:54:00+0000,my_repo,b9d9f290d4,trunk
2013-04-27T21:54:00+0000,my_repo,b9d9f290d4,trunk.comment.txt
2013-07-12T14:56:00+0000,my_repo,74814b7854,trunk
2013-07-12T14:56:00+0000,my_repo,74814b7854,trunk.comment.txt
2013-10-06T18:38:00+0000,my_repo,45dee4a06b,trunk
2013-10-06T18:38:00+0000,my_repo,45dee4a06b,trunk.comment.txt

Before creating the new repository, the extracted content can be modified by the user, and control files can be added in order to configure the building process, e.g. fix missing files or force the parent of an entry. The naming convention of the control files is described in the usage instructions.

If there’s a problem during the building, for example there are missing files or a check-in fails for any reason, a message is displayed and a terminal is open to let the user fix the problem manually (and also create the corresponding control file to manage the issue automatically the next time the building is tried).

Eventually the work directory will be ready to build automatically a new Fossil repository out of it.

Usage

  fossilisa ?OPTIONS? COMMAND ?OPTIONS?


COMMANDS

  extract

    Extract the content of a repository into a work directory.

  purge

    Purge files from the work directory.

  build

    Build a Fossil repository from the content of a work
    directory.

  help

    Display the full help.

  version

    Display the version.

OPTIONS (generic)

  -h|--help

    Display help about the given command instead of executing it.

  -n|--dry-run

    Display instead of run actions.

  --verbose

    Display more details about the actions.

OPTIONS (extract command)

  --from FILE|DIRECTORY

    Set the source to extract the content from. The three
    possible sources are checked in the following order:
    1) a Fossil repository file;
    2) a directory containing a <.git> directory;
    3) a directory containing backups, i.e. files having a
       date prefix in format 'YYYYmmddHHMM_'. Compressed
       archives are recognized and extracted.

  --to DIRECTORY

    Set the target work directory. An index file is created in
    this directory (use `--verbose` to see its name),
    containing the data from the repository timeline (Fossil)
    or log (Git), which then is used to make the entry
    directories and the comment control files.

  --repo-id LABEL

    Set the repository ID used in the entry directories. If
    not specified, the last directory of the repository path
    (Git) or the base filename (Fossil) is used and a warning
    is displayed.

  --branch BRANCH

    Set the Git branch name to be used in the entry directories
    instead of the default 'unknown'. The actual branch name
    cannot be extracted.

  -K|--keep-zip-archives

    Keep the temporary .zip archives in the work directory,
    instead of removing them. These archives are used to extract
    the content of a Fossil or Git repository. Their name is
    that of their corresponding entry directory. 

  --long-hash

    Use long hashes instead of short ones, in the entry
    directory names.

OPTIONS (purge command)

  --from DIRECTORY

    Set the work directory.

  -f|--file FILE

    Add 'FILE' to the list of files to be purged. This option
    can be repeated as many times as needed.

  -s|--since DATE

    Set given 'DATE' as the date of the first entry directory
    from which files will be deleted. All files specified by
    `-f | --file` will be deleted only in entry directories
    named with a date equal or newer than 'DATE', provided at
    least one such a directory exists. The date format is
    'YYYY-mm-ddTHH:MM+HHMM' (trailing parts can be ommited, but
    the minimum precision is 'YYYY-mm-dd').

    WARNING: The date must exist. If no such a date exists in
    the name of an entry directory, no file will be deleted.

OPTIONS (build command)

  --from DIRECTORY

    Set the source work directory.

  --to FILE

    Set the target Fossil repository file.

  -A|--admin-user USERNAME

    Select given 'USERNAME' as admin user.

NOTE: all of the long options are recognized also with a single
hyphen, e.g. `--help` and `-help` are equivalent.

CONTROL FILES

  The `build` command can be controlled by files created in the work
  directory and whose base names are those of the entry directories
  they affect. In the following description 'ENTRY' means the name
  of the corresponding entry directory.

  <ENTRY.branch.txt>

    This file contains the name of a new branch for the
    check-in. `--branch NAME` will be added to `fossil commit`,
    being 'NAME' the content of the file.

  <ENTRY.comment.txt>

    This file contains the check-in comment.

  <ENTRY.fish>

    This file is interpreted as a fish shell source after the
    checkout directory contains only the files of <ENTRY>, and
    before they are added to the repository. This file normally
    contains only `fossil rm` and `fossil mv` instructions to
    handle the missing files from the previous entry, but it can
    be used for other tasks, for example to add a tag to the
    previous check-in.

  <ENTRY.parent.txt>

    This file contains the name of the branch that will be the
    parent of the entry corresponding to <ENTRY>. This file
    forces a checkout of that parent branch, and adds `--branch
    NAME` to the commit of <ENTRY>, being 'NAME' the branch
    noted in <ENTRY>.

AUTHOR

  Marcos Cruz (programandala.net), 2021.

(Included in the source file.)

Disclaimer

Fossilisa has been successfully used to tidy and rebuild several repositories that were a mess because of Git, and also to restore the history of their renamed files, which is not preserved by a direct conversion from Git to Fossil.

Nevertheless Fossilisa is a work in progress and it may have bugs. There’s no warranty. The program does not modify the source repositories in any way, but making copies of them is always a good idea.

Fossilisa was written just to suit the needs of its author, and therefore it doesn’t support many possible features.

Author

Marcos Cruz (programandala.net), 2021.