youwen5/dartgun
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: update readme with new usage guide

Browse source
This commit is contained in:
Youwen Wu 2024-06-26 17:31:08 -07:00
parent 5ba2d5560f
commit 1b1f259c26
Signed by: youwen5
GPG key ID: 865658ED1FE61EC3
1 changed files with 101 additions and 63 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

164
README.md
View file

@ -1,17 +1,36 @@
# dartgun # dartgun
the stupid dotfile manager. the stupid dotfile manager
---
<!--toc:start-->
- [dartgun](#dartgun)
- [Impetus](#impetus)
- [Non-goals](#non-goals)
- [Goals](#goals)
- [How it works](#how-it-works)
- [Sample configuration](#sample-configuration)
- [Why symlinking?](#why-symlinking)
- [Why no Windows support?](#why-no-windows-support)
- [Installation Guide](#installation-guide)
- [Usage guide](#usage-guide)
- [License](#license)
<!--toc:end-->
---
## Impetus ## Impetus
Managing dot files are annoying. They're some of the most essential parts of a Managing dot files are annoying. They're some of the most essential parts of a
developer's system, yet most operating systems (distros) don't provide a way to developer's system, yet most operating systems (distros) don't provide a way to
easily manage them. There's the `~/.config` directory, which in theory holds all easily manage and version them. There's the `~/.config` directory, which in
of your configuration files. If this were true, you could simply `git init` theory holds all of your configuration files. If this were true, you could
inside `~/.config` and have a versioned dotfile repo that you could backup and simply `git init` inside `~/.config` and have a versioned dotfile repo that you
deploy to new machines. However, configuration files often end up all over a could backup and deploy to new machines. However, configuration files often end
system. There's [NixOS](https://nixos.org/), but not everyone can dedicate 40 up all over a system. There's [NixOS](https://nixos.org/), but not everyone can
hours a week to configuring their OS. dedicate 40 hours a week to configuring their OS.
Advanced dotfile helper solutions do exist, but what most users need doesn't Advanced dotfile helper solutions do exist, but what most users need doesn't
really amount to more than a set of bash scripts to copy their dotfiles around really amount to more than a set of bash scripts to copy their dotfiles around
@ -21,6 +40,10 @@ configuration files also ends up requiring the user to look through a
happened to happened to
[doing one thing, and doing it well](https://suckless.org/philosophy/)? [doing one thing, and doing it well](https://suckless.org/philosophy/)?
> Ingenious ideas are simple. Ingenious software is simple. [^1]
[^1]: Disclaimer: this software does not claim to be ingenious.
Dartgun's design statement is to be as simple as possible while providing just Dartgun's design statement is to be as simple as possible while providing just
enough features for most non power users. Anyone who reads through the example enough features for most non power users. Anyone who reads through the example
configuration files should be able to utilize all of dartgun's features configuration files should be able to utilize all of dartgun's features
@ -83,26 +106,64 @@ Dartgun is not for:
Dartgun allows you to centralize all of your dotfiles in a single directory. Dartgun allows you to centralize all of your dotfiles in a single directory.
Dartgun is configured through the `dartgun.toml` file. You should set your Dartgun is primarily configured through the `dartgun.toml` file, alongside the
machine name in this file like so: `machine.toml` file to specify machine-specific configuration. If you are using
`git` to version your dotfile directory, it is recommended that you add
`machine.toml` to your `.gitignore` since it contains configuration which should
not be shared across machines.
Currently, the only configuration option in `machine.toml` is the following:
```toml ```toml
machine = "youwens-mac" # file: machine.toml
identifiers = ["arch", "hypr", "etc"]
``` ```
Also, it's common to have programs that are not installed on every computer. The primary mechanism by which dartgun determines whether to install a given set
Therefore, each dotfile will specify which application it is for, and whether or of dotfiles to a system is through the _identifiers_. These are simply strings
not it should be applied by default. See the dotfile configuration below for how that can represent whatever you want. You configure a set of identifiers for
to configure this. your system in `machine.toml`, and specify which identifiers a given dotfile
applies to in the `dartgun.toml` file.
You can specify which applications are in which machines with the `apps.toml` This is useful for installing distribution-specific files (like macOS, Arch
file. Linux, and Fedora specific files), or for applications which you do not always
install on every system.
### Sample configuration
Here is the structure of `dartgun.toml`:
```toml ```toml
[youwens-mac] # file: dartgun.toml
available = ["neovim", "hyprland", "zsh"]
[[dots]]
# the location of the original files, in the dartgun directory. Can be relative or absolute.
location = "./nvim"
#
# The destination which to place the file at. MUST BE AN ABSOLUTE PATH.
destination = "/home/youwen/Projects/Mine/2024/dartgun/dartgun-test/target/nvim"
#
# Whether to use symbolic linking or hard linking. Symlinking is recommended and
# should be used unless there is a reason to use hard links instead.
# Keep in mind hard linking does NOT work on directories.
strategy = "symlink"
#
# The machine identifiers that this dotfile will match. If the identifiers listed
# in a `machine.toml` match ANY of the identifiers in this list, it will be copied on that machine.
identifiers = ["linux", "arch", "neovim"]
[[dots]]
location = "./.zshrc"
destination = "/home/youwen/.zshrc"
strategy = "symlink"
identifiers = ["linux", "macos"]
``` ```
As shown, each separate dotfile directory or file should be prefixed with
`[[dots]]` (technical note: this represents an array of objects in TOML, where
each entry under `[[dots]]` is an object in the array).
### Why symlinking? ### Why symlinking?
Any configuration updates made will always sync back to the dartgun directory so Any configuration updates made will always sync back to the dartgun directory so
@ -114,6 +175,10 @@ automatically reflected in the system for free.
Windows symlinks work a little differently from Unix symlinks. The difference is Windows symlinks work a little differently from Unix symlinks. The difference is
not massive and I plan to look into supporting Windows at a later date. not massive and I plan to look into supporting Windows at a later date.
## Installation Guide
`dartgun` can be built and installed from source through Rust's `cargo`.
## Usage guide ## Usage guide
Begin by creating a folder to place your dotfiles in. I'll refer to it as the Begin by creating a folder to place your dotfiles in. I'll refer to it as the
@ -121,56 +186,29 @@ Begin by creating a folder to place your dotfiles in. I'll refer to it as the
`~/.dartgun`, but it can be called whatever you want and located wherever you `~/.dartgun`, but it can be called whatever you want and located wherever you
want it. want it.
Place your dotfiles in the dartgun folder. You can organize them however you In this directory, create two files called `machine.toml` and `dartgun.toml`.
want. The primary configuration is done in the `dartgun.json` file, located in Then, populate it with all of the dotfiles which you would like dartgun to
root of the dartgun folder. In here, you specify where each file or folder in manage.
the directory goes.
For example, I can tell the `.dartgun/nvim` folder to go to `~/.config/nvim` Read [the example configuration files](#sample-configuration) to learn how to
with configure your `machine.toml` and `dartgun.toml`.
```json Note that the identifiers system lets you choose how you want to approach the
{ machine configuration. You can either have a specific identifier for each
darts = [ computer you own, or specify identifier by platform (eg. "arch", "mac",
{ "fedora"), or specify identifiers by application (eg. "neovim", "hyprland",
location: "./nvim", "zsh"). You can also combine all three, and come up with other identification
destination: "~/.config/nvim", schemes to fit your needs. You can get as fine-grained or generic as you'd like.
strategy: "hardlink",
machines: [youwens-mac, youwens-archlinux],
for: "neovim"
}
]
}
```
``` Then, run `dartgun fire` to apply your dotfiles to the locations. For nested
location: the relative path, from the dartgun folder, where either the directory or file to be copied is located destination directories, it will attempt create all of the directories in the
destination: the destination path to which the file should be copied to. must be an absolute path path if they do not exist already. You may have to run `dartgun fire` with
strategy: which strategy to use to copy the file. accepts 'hardlink', 'symlink', or 'copy' superuser privileges if you are trying to copy files to restricted locations.
machines: which machine names this file will be copied on
for: the application which the dotfile is for
```
Note that you can choose how you want to approach the machine configuration. You Because the files are symlinked or hardlinked, you can simply sync your dotfiles
can either have a specific machine key for each computer you own, or specify by updating them in the dartgun folder, for example by running `git pull` after
machines by platform (eg. "arch", "mac", "fedora"). You can get as fine-grained
or generic as you'd like.
Then, run `dartgun blast` to apply your dotfiles to the locations. For nested
destination directories, it will create all of the directories in the chain if
they do not exist already. You may have to run `sudo dartgun blast` if you are
trying to copy files to restricted locations.
For symlinked and hardlinked directories, you can simply sync your dotfiles by
updating them in the dartgun folder, for example by running `git pull` after
you've set up git versioning. you've set up git versioning.
If you use the `copy` strategy, then you need to re-run `dartgun blast` each
time you update the files in your dartgun folder. generally, we do not recommend
the copy method unless you have to for some reason, since it may lead to desyncs
between the dartgun folder and your actual system, while this is impossible with
hardlinking or symlinking.
## License ## License
This project is licensed under [GPLv3](./LICENSE). This project is free software under the [GPL v3](./LICENSE).