The idea is to be able to replicate a certain setup (when reseting your machine or using a completely new machine). Additionally, it should be possible to update the setup easily when needed, e.g. an update to your vim config files. So, it will help with managing dotfiles, symlinks, etc.
A real world example can be found in my .dotfiles repository.
You can also use it for other tasks such as making the onboarding process of a new colleague easier by providing them a config that installs certain dependencies and checks out important repositories.
Install via cargo or download a binary from the release page.
bash
cargo install machine_setup
| command | description | example |
| --------- | ----------------------------- | ------------------------- |
| install | install the defined tasks | machine_setup install |
| update | update the defined tasks | machine_setup update |
| uninstall | uninstall the defined tasks | machine_setup uninstall |
| list | list all of the defined tasks | machine_setup list |
By default, machine_setup will look for a file called machine_setup with a supported file format.
Supported file formats are: yaml, yml, and json.
| flag | value | example |
| ---------------- | ------------------------------------------- | ------------------------------------------------- |
| -c
--config | specify a different path to the config file | machine_setup install -c ./config/my_setup.yaml |
| -t
--task | only run the specified task | machine_setup install -t my_task2 |
| -s
--select | select a task to run | machine_setup install -s |
| -h
--help | display help information | machine_setup --help |
| -v
--version | display version information | machine_setup --version |
The supported formats are YAML and JSON.
Tasks can be defined under the tasks root key.
Every task can contain an arbitrary number of commands.
| key | description | values | default |
| ------------- | ---------------------------------------------------- | ------------- | ------------------ |
| tasks | root key for all of the tasks | |
| defaultshell | shell that is used when not specified by the command | bash, zsh | bash |
| tempdir | define where temporary files are stored | | ~/.machine_setup |
| key | description | values | examples | | --- | ---------------------------- | ---------------------------------------------------------------------------- | ----------------------------- | | os | only run on the specified os | possible values | "linux" or ["linux", "macos"] |
TODO: Add JSON examples...
Check out the example configuration below:
```yaml tempdir: "~/mytemp" # defaults to "~/.machinesetup" defaultshell: "zsh" # defaults to "bash" tasks: mytask1: os: ["linux", "windows"] commands: - copy: src: "./src/files" target: "/tmp/target" - copy: src: "./src/files2" target: "/tmp/target"
my_task2: os: ["linux"] commands: - shell: "sudo apt-get install git -y" - symlink: src: "./src/config" target: "~/.dotfiles" ```
Extensibility is not explicitly built in.
However, it's possible to execute tasks from another configuration via the run command.
You could also only execute a single task by providing the task argument.
yaml
tasks:
my_other_config:
commands:
- run:
commands:
install: "machine_setup install -c ./my_other_config.yaml"
update: "machine_setup update -c ./my_other_config.yaml"
uninstall: "machine_setup uninstall -c ./my_other_config.yaml"
This command copies the contents of a directory to another directory.
| argument | value | required | example | | -------- | ----------------------------------- | :------: | -------------------------------------- | | src | source directory/file | ✅ | "./src/files" or "./src/test.txt" | | target | target directory/file | ✅ | "/tmp/target" or "/tmp/target/new.txt" | | ignore | list of files/directories to ignore | ➖ | ["dist", "package-lock.json"] |
yaml
copy:
src: "./src/files"
target: "/tmp/target"
ignore: ["dist", "package-lock.json"]
This command clones a git repository to the specified destination.
| argument | value | required | example | | -------- | ----------------------- | :------: | ------------------------------------------- | | url | URL to a git repository | ✅ | "git@github.com:Chroma91/machinesetup.git" | | target | target directory | ✅ | "~/machinesetup" |
yaml
clone:
url: "git@github.com:Chroma91/machine_setup.git"
target: "~/machine_setup"
This command symlinks all the files from the source directory to the target directory.
| argument | value | required | example | | -------- | ----------------------------------- | :------: | --------------------------------- | | src | source directory/file | ✅ | "./src/files" or "./src/test.txt" | | target | target directory/file | ✅ | "/tmp/target" or "/tmp/new.txt" | | ignore | list of files/directories to ignore | ➖ | ["dist", "package-lock.json"] | | force | true/false | ➖ | |
If
forceis set totrue, existing files will be removed and replaced by the symlinks.
yaml
symlink:
src: "./src/files"
target: "/tmp/target"
ignore: ["dist", "package-lock.json"]
force: true
This command executes a shell command.
Hint: Avoid the usage of interactive commands when possible.
| argument | description | required | default | values | | -------- | --------------------- | :------: | ------- | ------------- | | env | environment variables | ➖ | | | | shell | shell that is used | ➖ | "bash" | "bash", "zsh" |
By default, shell commands will be skipped when updating or uninstalling.
You can change that by prodiving update and/or uninstall.
The following arguments can be passed to commands:
| argument | description | required | example | | --------- | ------------------------ | :------: | ------------------------------- | | install | command for installing | ➖ | "sudo apt-get -y install git" | | update | command for updating | ➖ | "sudo apt-get -y upgrade git" | | uninstall | command for uninstalling | ➖ | "sudo apt-get -y uninstall git" |
```yaml inline_command: run: commands: "sudo apt-get -y install git"
multiline_command: run: commands: - "sudo apt-get update" - "sudo apt-get -y install git"
updatablecommand: run: env: SOMETOKEN: "abc123" commands: install: "sudo apt-get -y install git" update: "sudo apt-get -y upgrade git" uninstall: "sudo apt-get -y uninstall git"
updatablemultilinecommand: run: env: SOME_TOKEN: "abc123" commands: install: - "sudo apt update" - "sudo apt-get -y install git" update: - "sudo apt-get -y upgrade git" - ... uninstall: - "sudo apt-get -y uninstall git" - ... ```
--verbose flagcopy and symlink as root user (needed to move/link some system files)[BREAKING]
dependsOn can be set for tasks to make them wait for other tasks