168 lines
7.7 KiB
Markdown
168 lines
7.7 KiB
Markdown
### 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](https://linux.die.net/man/8/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.
|
|
|
|
```bash
|
|
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](https://rustup.rs/) to setup the Rust toolchain
|
|
|
|
To build and install `kot` run the following commands
|
|
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
*
|