From eabc227c093a5d54d0d2c05be0fe435d2a22b3fb Mon Sep 17 00:00:00 2001 From: Shaun Reed Date: Wed, 29 Dec 2021 14:58:30 -0500 Subject: [PATCH] WIP Commit + Update README to use cargo install instructions --- README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 64 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 4258902..b821306 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,91 @@ -#### kot +### kot -Learning to program in Rust by making myself a Linux CLI tool to help manage dotfiles and configurations. -There are many other tools to manage dotfiles that work just fine. For now, this is intended to be just for my own learning / use and not a general dotfiles management utility. +`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 directory, using any target directory. To test how `kot` might behave, +you could point `--install-dir` to any directory that you've created for testing. +This directory could be empty, or it could contain another set of dotfiles. `kot` will attempt + to install the configurations. If conflicts are detected, output shows the conflicts and +prompts to abort or continue. An example of this is seen below. + +```bash +kot dotfiles/dot/ + +args: Cli { dotfiles_dir: "/home/kapper/Code/kot/dotfiles/dot", install_dir: "/home/kapper/Code/kot/dry-runs/kapper", backup_dir: "/home/kapper/Code/kot/backups/kapper", force: false } + +The following configurations already exist: + "/home/kapper/Code/kot/dry-runs/kapper/.bashrc" + "/home/kapper/Code/kot/dry-runs/kapper/.config" + "/home/kapper/Code/kot/dry-runs/kapper/README.md" + "/home/kapper/Code/kot/dry-runs/kapper/VimScreenshot.png" + "/home/kapper/Code/kot/dry-runs/kapper/fix-vbox.sh" + "/home/kapper/Code/kot/dry-runs/kapper/.git" + "/home/kapper/Code/kot/dry-runs/kapper/.bash_aliases" + "/home/kapper/Code/kot/dry-runs/kapper/.gitignore" + "/home/kapper/Code/kot/dry-runs/kapper/.gitmodules" + "/home/kapper/Code/kot/dry-runs/kapper/.vimrc" + "/home/kapper/Code/kot/dry-runs/kapper/.vim" +If you continue, backups will be made in "/home/kapper/Code/kot/backups/kapper". Any configurations there will be overwritten. +Abort? Enter y/n or Y/N: +``` + +If there are already files within the backup directory, `kot` will exit and show an error message. +This is to protect existing backups from being merged with configs from subsequent runs. +If you want to erase these backups and create a new backup, rerun the command with the `--force` flag set. +Otherwise, specify a different backup directory with the `--backup-dir` option. +If the backup directory does not exist, it will be created. + + +```bash +kot dotfiles/dot/ + +thread 'main' panicked at ' + Error: Backups already exist at "/home/kapper/Code/kot/backups/kapper" + Set the --force flag to overwrite configurations stored here', src/kot/kcli.rs:94:17 +note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace +``` + +#### Installation Follow [Rustup instructions](https://rustup.rs/) to setup the Rust toolchain -Then to build and run `kot`, run the following commands +To build and install `kot` run the following commands ```bash git clone https://gitlab.com/shaunrd0/kot && cd kot -cargo build -./target/debug/kot --help +cargo install --path . +kot --help kot 0.1.0 -CLI utility for managing Linux user configurations +CLI for managing Linux user configurations USAGE: - kot [OPTIONS] + kot [FLAGS] [OPTIONS] FLAGS: + -f, --force Overwrites existing backups -h, --help Prints help information -V, --version Prints version information OPTIONS: - --backup-dir The location to store backups for this user [default: backups/kapper] - --home-dir The location to attempt installation of user configurations [default: dry- - runs/kapper] + -b, --backup-dir The location to store backups for this user [default: backups/kapper] + -i, --install-dir The location to attempt installation of user configurations [default: dry- + runs/kapper] ARGS: - Local or full path to user configurations to install + Local or full path to user configurations to install ``` +#### Dotfiles Management + To store dotfiles, this repository uses submodules. To update surface-level submodules, we can run the following commands ```bash git submodule update --init + Submodule path 'dot': checked out '7877117d5bd413ecf35c86efb4514742d8136843' ``` @@ -70,4 +122,3 @@ Submodule path 'dotfiles/dot/.vim/bundle/vim-airline': checked out 'cb1bc19064d3 Submodule path 'dotfiles/dot/.vim/bundle/vim-airline-themes': checked out 'd148d42d9caf331ff08b6cae683d5b210003cde7' Submodule path 'dotfiles/dot/.vim/bundle/vim-signify': checked out 'b2a0450e23c63b75bbeabf4f0c28f9b4b2480689' ``` -