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 (support for Mercurial repositories is under development).
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.
fossilisa ?OPTIONS? COMMAND ?OPTIONS?
COMMANDS
extract
Extract the content of a repository into a work directory.
Options:
--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.
purge
Purge files from the work directory.
Options:
--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.
--branch BRANCH
Set a filter to purge only the files that are in entry
directories that belong to the given `BRANCH`.
NOTE: The branch of an entry directory is the part of its
name situated after the last comma.
build
Build a Fossil repository from the content of a work
directory.
Options:
--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.
mmv ?OPTIONS?
Perform a 'multiple move', i.e. a batch version of `mv`.
First open the editor with two parallel lists: the missing files
on the left side and the extra files on the right side. Then
let the user sort them to make the names match, i.e. line
1 on the left side contains the old filename, while line 1 on the
right side contains its new name.
When the editor is closed by the user, execute `fossil rename`
with the contents of every pair of lines.
Options:
-e|--editor 'EDITOR options'
Editor to use, with its required options to open the files
in vertical windows. If this option is not used, and Neovim
is installed in the system, `nvim -O` is used; otherwise, if
Vim is installed, `vim -O` is used. Otherwise the content
of the `$EDITOR` system variable is used, and the user
must configure its windows.
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.
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, 2022.
(Included in the source file.)
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.
Marcos Cruz (programandala.net), 2021, 2022.