cfgrr (Configurer)

cfgrr is a tool to help manage the myriad of config files usually found on your Linux setup. If you're familiar with GNU stow, you'll find cfgrr to be an opinionated replacement for stow with a much more guided setup.

At the time of typing this, Jan 2023, cfgrr should be able to find all your config files, add them to some kind of directory structure, track them with git, and give you the option to push them to your private git remote, and restore them at will.

Disclaimer

This tool was tested on Linux systems only, though it should also work with macOS. It also confusingly works on Windows too (though I don't recommend using it there).

Installation

Using go install

go install github.com/osamaadam/cfgrr@latest

Download the binary

Download the latest binary for your respective platform from the latest release

-or-

Install from source

Note: You need to have Go installed.

First, clone the repository:

git clone https://github.com/osamaadam/cfgrr.git

Then run the installation script:

make install

The binary would be installed at ${HOME}/go/bin/cfgrr

TL;DR

To back up:

cfgrr b ~/

Then choose the files you'd like to back up.

✨ Poof! A backup of your files will be at ~/.config/cfgrr.

To restore:

(assuming you have the backup folder at ~/.config/cfgrr)

cfgrr r -a

Current progress

Currently, cfgrr is able to find config files matching certain patterns (currently "**/.*", and "**/*config*"). It is also able to restore backed up files.

Usage

Backup:

⚠️ WARNING ⚠️ backup will copy the files to the backup directory, and replace them with symlinks to their equivalent in the backup directory.

This will back up all the config files found in the given directory.

cfgrr backup [root_path] [...files]

🔔 You'll be prompted to choose the files you'd like to back up.

To skip the prompt, use the --all flag.

cfgrr backup ~/dotfiles/ -a

🔍 For more info, run cfgrr backup --help.

Examples:

cfgrr backup ~/.config

cfgrr b ~/.bashrc ~/.zshrc

This will back up all the config files found in ~/.config matching the pattern **/.* or **/*config* (default patterns).

Restore:

⚠️ WARNING ⚠️ restore will replace the files from the described paths (paths in cfgrrmap.yaml) with symlinks to their equivalent in the backup directory.

This will restore all the backed up files to their original locations.

cfgrr restore

🔍 For more info, run cfgrr restore --help.

Example:

cfgrr r -d ~/cfgrr/

This will prompt you to choose the files you'd like to restore from the backup directory ~/cfgrr/.

If you'd like to restore all the files, you can use the -a flag.

cfgrr r -a

Set:

This is an interface to set the config values for cfgrr.

The config values are stored in ~/.cfgrr.yaml by default.

cfgrr set [key] [value]

🔍 For more info, run cfgrr set --help.

Example:

cfgrr set backup_dir ~/cfgrr

Unset:

This is an interface to unset the config values for cfgrr.

cfgrr unset [key]

🔍 For more info, run cfgrr unset --help.

Example:

cfgrr unset backup_dir

Setup:

This is an interface to set up cfgrr for the first time.

cfgrr setup

You'll then be prompted to choose the various config values for cfgrr.

🔍 For more info, run cfgrr setup --help.

Delete:

This subcommand allows the user to delete backed up files from the backup directory.

cfgrr delete [...files]

If the user were to use the --restore flag, the symlinks created previously would be replaced by the file from the backup directory. This is a safe way of undoing your backups.

cfgrr delete --restore [...files]

In case no files were provided to the argument, the user will be prompted to choose the files to delete.

🔍 For more info, run cfgrr delete --help.

Replicate:

Creates a browsable replica of the files. Could be useful if the user may want to share the files in a manner that's human-readable.

cfgrr replicate

By default, this creates the replica at .config/cfgrr/home/ (assuming the user is using default configurations) or generally at BACKUP_DIR/home/.

To generate the replica at a different location:

cfgrr replicate ~/path/to/replica

The path must be absolute, otherwise the tool would assume the path is relative to the backup directory.

You know the drill by this point, to skip the prompt, use --all flag.

cfgrr replicate --all

🔍 For more info, run cfgrr replicate --help.

Push:

This subcommand allows the user to push the backed up files to a remote git repository.

cfgrr push

By default, this will push the changes to the remote origin on the current branch.

To push to a different remote or branch:

cfgrr push origin backup-branch

🔍 For more info, run cfgrr push --help.

Clone:

This subcommand allows the user to clone the backed up files from a remote git repository. If a repository already exists, the latest changes will be pulled instead.

cfgrr clone <remote_url>

By default, this will clone the branch master. To clone a different branch:

cfgrr clone git@github.com:osamaadam/cfgrr.git --branch backup-branch

🔍 For more info, run cfgrr clone --help.