This program captures your home directory and synchronize it with another host using Git repo metadata, symbolic links and persisted files.

I wrote this because I couldn't find anything that creates repositories with the idea of having a portable and easy to recreate your home directory on another host. If I've reinvented the wheel, please let me know :)

More specifically: it persists and creates build out environments in a nascent account. The program memorizing a users home directory and building it out on another system (see overview). This is done by:

1. Copying files, directories and git repos configuration.
2. Creating a distribution compressed file.
3. Uncompress on the destination system and create repos.

A future release will also synchronize and manage multiple GitHub repositories.

A utility script also provided to do operations on all configured local git repositories.

See the full documentation. The API reference is also available.

The easist way to install the command line program is via the pip installer:

pip install zensols.grsync

Binaries are also available on pypi.

Not only is the aim to create a repproducable development (or like) environment, it is also to create a clean environment. This means we have temporary directories we might expect to exist for our process(es), and of course repositories cloned in their nascent state. These steps are summarized below:

1. Freeze: This process captures the current host's setup and configuration (specified in the configuration file) and includes:

• Empty directories.
• Git repository meta data.
• Locations of files to copy, top level directories of files to recursively copy, where symlinks are considered files as well and currently not followed. See caveat.

A sub-step of this process is discover, which reads the file system as indicated by the configuration file. This includes reading git repostiory metadata, identifying file metadata (i.e. permissions) etc.

1. Bootstraping: create an Python virtual environment on the target machine that can be loaded with this program and depenedencies. This is not a necessary step as the program is available as a pip install. However, if this step can be used to help automate new environments, after which, you could futher add/install software with tools such as Puppet.
2. Thaw: This includes two steps:
3. File Extraction: extracts the files from the distribution zip created in the freeze step.
4. Repo Cloning: this step recursively clones all repositories.

The program has two phases: freeze and thaw (see overview). The command line program is used twice: first on the freeze on the source system and then thaw on the target machine.

See usage for more information.

The configuration is used the freeze phase to create the distribution file. This fil contains all git repositories, files, empty directory paths on the current file system that is stored to be thawed on the target system.

See configuration for detailed documentation on configuration test case yaml file for an example of a simple configuration file to capture a set of git repositories and small set of files. The freeze/thaw/move test case uses this configuration file, which is more comprehensive and up to date.

As mentioned in the usage section, symbolic links pointing to any file in a repository are froozen, which means that integrity at thaw time is ensured. However, links not pointing to a repository are persisted, but the files and directories they point to are not.

A future release might have a follow symbolic links type functionality that allows this. However, for now, you must include both the link and the data it points to get this integrity.

An extensive changelog is available here.

Please star this repository and let me know how and where you use this API. Contributions as pull requests, feedback and any input is welcome.

MIT License

Copyright (c) 2020 - 2023 Paul Landes