kot

kot is a CLI for managing Linux dotfiles configurations that helps to automate the setup process across various applications without risking the loss of local configurations currently on the system. This helps to protect against installing broken dotfiles by providing a way to reverse the installation and return the system back to the previous state.

The installation process creates symbolic links, much like what you would expect when using stow. kot can install dotfiles from any source directory, to any target directory. To test how kot might behave, you could point --install to any directory that you've created for testing. This directory could be empty, or it could contain another set of dotfiles. Alternatively, you could set the --dry-run flag that will automatically install to a predefined path ($HOME/.local/share/kot/dry-runs/$USER) Note that this directory will never be cleared automatically, each subsequent --dry-run will stack configurations into this default directory until it is manually cleared.

If conflicts are detected, kot shows the conflicts found and prompts to abort or continue. An example of this is seen below. This prompt will be skipped if the --force flag is set.

kot --dry-run dotfiles/dot/

args: Cli { dotfiles: "/home/kapper/Code/kot/dotfiles/dot", install_dir: "/home/kapper/.local/share/kot/dry-runs/kapper", backup_dir: Some("/home/kapper/.local/share/kot/backups/dot:2022-05-29T19:03:27"), clone_dir: None, force: false, dry_run: true, is_repo: false, conflicts: [] }
The following configurations already exist:
  "/home/kapper/.local/share/kot/dry-runs/kapper/.git"
  "/home/kapper/.local/share/kot/dry-runs/kapper/.vimrc"
  "/home/kapper/.local/share/kot/dry-runs/kapper/.bash_aliases"
  "/home/kapper/.local/share/kot/dry-runs/kapper/.vim"
  "/home/kapper/.local/share/kot/dry-runs/kapper/VimScreenshot.png"
  "/home/kapper/.local/share/kot/dry-runs/kapper/.gitignore"
  "/home/kapper/.local/share/kot/dry-runs/kapper/.config"
  "/home/kapper/.local/share/kot/dry-runs/kapper/fix-vbox.sh"
  "/home/kapper/.local/share/kot/dry-runs/kapper/.gitmodules"
  "/home/kapper/.local/share/kot/dry-runs/kapper/.bashrc"
  "/home/kapper/.local/share/kot/dry-runs/kapper/README.md"
If you continue, backups will be made in "/home/kapper/.local/share/kot/backups/dot:2022-05-29T19:03:27". 
Any configurations there will be overwritten.
Continue? Enter Y/y or N/n:

User Data

kot stores user data within $HOME/.local/share/kot/

When we provide a repository URL as our dotfiles to install, the repo will be recursively cloned into $HOME/.local/share/kot/dotfiles/<REPO_NAME>. This is to ensure each user of kot maintains their own dotfiles in a location that is accessible but not easy to accidentally modify or erase. If needed, the user can provide a preferred clone directory to the CLI by setting the --clone-dir option

When we encounter conflicts during installation of these dotfiles, backups will be created in $HOME/.local/share/kot/backups/<DOTFILES_NAME>:<DATE(%Y-%m-%dT%H:%M:%S)> If there are no conflicts found during installation, no backup is created. Configurations are said to be conflicting if the --install path contains configuration files that are also within the dotfiles we are currently installing.

Backups are intended to reverse changes applied during installation of dotfiles. These backups are not exhaustive of all configurations tied to the system or user. The backups only include files that were direct conflicts with configurations being installed. When we reach an error during installation, kot will restore the configurations within the last backup, and then removes unused configurations.

Installing kot

Follow Rustup instructions to setup the Rust toolchain

To build and install kot run the following commands

git clone https://gitlab.com/shaunrd0/kot && cd kot
cargo install --path .
kot --help

kot 0.1.5
CLI for managing Linux user configurations

USAGE:
    kot [FLAGS] [OPTIONS] <dotfiles> --install <install>

FLAGS:
    -d, --dry-run
            Installs configurations to $HOME/.local/shared/kot/dry-runs

            Useful flag to set when testing what an install would do to your home directory. This is synonymous with
            setting --install $HOME/.local/shared/kot/dry-runs/$USER. Subsequent runs with this flag set will not delete
            the contents of this directory.
    -f, --force
            Overwrites existing backups

            This flag will replace existing backups if during installation we encounter conflicts and the backup-dir
            provided already contains previous backups.
    -h, --help
            Prints help information

    -V, --version
            Prints version information


OPTIONS:
    -b, --backup-dir <backup-dir>
            The location to store backups for this user

            If no backup-dir is provided, we create one within the default kot data directory:
            $HOME/.local/share/kot/backups/
    -c, --clone-dir <clone-dir>
            An alternate path to clone a dotfiles repository to

            If the clone-dir option is provided to the CLI, kot will clone the dotfiles repository into this directory.
            If clone-dir is not provided, the repository is cloned into $HOME/.local/share/kot/dotfiles Custom clone-dir
            will be used literally, and no subdirectory is created to store the cloned repository For example, clone-dir
            of $HOME/clonedir for repo named Dotfiles We will clone into $HOME/clonedir, and NOT $HOME/clonedir/Dotfiles
            The default path for cloned repos is $HOME/.local/share/kot/dotfiles/
    -i, --install <install>
            The location to attempt installation of user configurations

            The desired installation directory for user configurations. By default this is your $HOME directory This
            could optionally point to some other directory to perform a dry run, or the --dry-run flag could be set
            [env: HOME=/home/kapper]

ARGS:
    <dotfiles>
            Local or full path to user configurations to install. Can also be a git repository.

            System path or repository URL for dotfiles we want to install. If a path is used, it can either be local to
            CWD or absolute. If a URL is used for a dotfiles repository, the repo is cloned into
            $HOME/.local/shared/kot/dotfiles/

If you don't want to install kot, you can also use the following cargo command where all arguments after the -- are passed as arguments to kot and not cargo. Below is an example of the short-help output text provided with the -h flag

cd path/to/kot
cargo build
cargo run -- --help


kot 0.1.5
CLI for managing Linux user configurations

USAGE:
    kot [FLAGS] [OPTIONS] <dotfiles> --install <install>

FLAGS:
    -d, --dry-run    Installs configurations to $HOME/.local/shared/kot/dry-runs
    -f, --force      Overwrites existing backups
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -b, --backup-dir <backup-dir>    The location to store backups for this user
    -c, --clone-dir <clone-dir>      An alternate path to clone a dotfiles repository to
    -i, --install <install>          The location to attempt installation of user configurations [env:
                                     HOME=/home/kapper]

ARGS:
    <dotfiles>    Local or full path to user configurations to install. Can also be a git repository

TODO

• Ensure empty backups are not created
• Provide interface for managing agreed-upon /etc/skel/ configurations
• Provide more CLI options for git functionality; Branches, update submodules, etc
• Clean up warnings during build / installation
• Automate testing