coliru

A minimal, flexible, dotfile installer
git clone https://git.ashermorgan.net/coliru/
Log | Files | Refs | README

README.md (4439B)

      1 # coliru
      2 
      3 A minimal, flexible, dotfile installer
      4 
      5 [![asciicast](https://asciinema.org/a/680428.svg)](https://asciinema.org/a/680428)
      6 
      7 ## Features
      8 
      9 With coliru you can:
     10 
     11 - Install dotfiles as copies and/or symlinks
     12 - Manage differences between machines using tags
     13 - Run custom scripts
     14 - Install dotfiles on remote machines over SSH
     15 
     16 ## Installation
     17 
     18 Coliru binaries can be downloaded from the
     19 [GitHub releases page](https://github.com/ashermorgan/coliru/releases).
     20 
     21 Coliru can also be installed from source using Cargo:
     22 
     23 ```
     24 CARGO_NET_GIT_FETCH_WITH_CLI=true cargo install --git https://git.ashermorgan.net/coliru/
     25 
     26 # To uninstall:
     27 # cargo uninstall coliru
     28 ```
     29 
     30 ## Usage
     31 
     32 Dotfile metadata is stored in a manifest file as a series of steps that can be
     33 executed conditionally based on tag rules. To install dotfiles, pass the
     34 location of the manifest file and the desired tag rules:
     35 
     36 ```
     37 coliru manifest.yml --tag-rules tag1 tag2,tag3 ^tag4
     38 ```
     39 
     40 Some other helpful options include:
     41 
     42 - `--help`, `-h`: Print full help information
     43 - `--list-tags`, `-l`: List the tags in the manifest and quit without installing
     44 - `--dry-run`, `-n`: Do a trial run without any permanent changes
     45 - `--host <HOST>`: Install dotfiles on another machine over SSH
     46 - `--copy`: Interpret link commands as copy commands
     47 
     48 ### Manifest File
     49 
     50 Manifests are defined using YAML as an array of steps that are executed to
     51 install the dotfiles, which are located in the same directory as the manifest.
     52 Each step may contain an array of copy, link, and/or run commands, in addition
     53 to an array of tags (see below). Each command is run from the directory
     54 containing the manifest file, or relative to the `~/.coliru` directory when
     55 installing over SSH.
     56 
     57 - The **copy** command copies a dotfile (`src`) to a destination (`dst`).
     58   Missing parent directories are created automatically.
     59 - The **link** command links a dotfile (`src`) to a destination (`dst`) using
     60   symbolic links on Unix and hard links on Windows. Missing parent directories
     61   are created automatically and coliru will run copy commands in place
     62   of link commands when installing over SSH.
     63 - The **run** command executes a script (`src`) from the command line, using
     64   `sh` on Unix and `cmd` on Windows, with an optional `prefix` (e.g. `python3`)
     65   or `postfix` (e.g. `arg1 arg2 arg3`) string. Inside `postfix`, `$COLIRU_RULES`
     66   will be expanded into a space-delimited list of the current tag rules. When
     67   installing over SSH, scripts are copied to the `~/.coliru` directory on the
     68   remote machine before they are executed.
     69 
     70 Example YAML manifest (see `examples/basic/` for a complete example dotfile
     71 repository):
     72 
     73 ```yml
     74 steps:
     75   - copy:
     76     - src: gitconfig
     77       dst: ~/.gitconfig
     78     tags: [ windows, linux, macos ]
     79 
     80   - link:
     81     - src: bashrc
     82       dst: ~/.bashrc
     83     - src: vimrc
     84       dst: ~/.vimrc # Will create symbolic links on Linux & MacOS
     85     run:
     86     - src: ./script.sh
     87       prefix: sh # unecessary on Unix if script.sh is executable
     88       postfix: arg1 $COLIRU_RULES
     89     tags: [ linux, macos ]
     90 
     91   - link:
     92     - src: vimrc
     93       dst: ~/_vimrc # Will create hard link on Windows
     94     run:
     95     - src: script.bat
     96       postfix: arg1 $COLIRU_RULES
     97     tags: [ windows ]
     98 ```
     99 
    100 ### Tags and Tag Rules
    101 
    102 Tags enable the installation of a subset of manifest steps based on a set of tag
    103 rules. Tags are user-defined and may be used to specify a step's supported
    104 operating systems (e.g. `linux`, `macos`, and/or `windows`), privilege
    105 requirements (e.g. `system` vs `user`), or even the types of machines it applies
    106 to (e.g. `personal`, `work`, `server`, etc).
    107 
    108 Tag rules are specified on the command line using the `--tag-rules` option. In
    109 order for the commands in a step to be executed, its tags must satisfy all of
    110 the tag rules. If no tags rules are provided, all manifest steps will be
    111 executed. Each tag rule contains a comma separated list of tags that can satisfy
    112 the rule. A leading caret (`^`) will negate the entire rule.
    113 
    114 In other words, commas correspond to OR, carets to NOT, and the spaces between
    115 rules to AND. So `--tag-rules A B,C ^D,E` looks for steps with the tags `A && (B
    116 || C) && !(D || E)`.
    117 
    118 ## Development
    119 
    120 Use Cargo to build, test, and run coliru:
    121 
    122 ```
    123 cargo build
    124 cargo test
    125 cargo run -- --help
    126 ```
    127 
    128 Some of coliru's integration and end-to-end tests interact with a test SSH
    129 server, which can be started with Docker Compose:
    130 
    131 ```
    132 docker compose -f tests/server/compose.yml up
    133 ```