# symp
`symp` (short for **sym**_link_ **p**_ackages_) is a symlink manager for
your system. It is a simple, yet flexible alternative to
GNU's `stow` that I created for managing my dotfiles, but can be used more
broadly to aid in cross-distribution package installation.
# Features
- Define symlinks and their sync behavior declaratively in `symp.toml` files.
- Supports grouping symlinks into logical units called 'packages', which can
be independently synced to your system.
- Fast fail: no symlinks are created/destroyed unless _all_ symlinks can be
created/destroyed.
- Local system state tracked via `symp.lock` files.
# Installation
`symp` is available on [crates.io](https://crates.io/crates/symp) and can be
installed via cargo:
`cargo install symp`
Currently, only unix systems are officially supported.
# Getting Started
## Creating your first `symp.toml` file
To start using `symp`, you first need to create a `symp.toml` file*. In the
`examples/dotfiles` directory of this repository, there is a heavily commented
[symp.toml](examples/dotfiles/symp.toml) file that you can use as an example.
The comments in this file walkthrough the available configuration settings, as
well as give you a sense of what all you can do with just a single `symp.toml`
file. For a complete reference of the available settings, refer
to the [symp.toml reference](docs/settings.md) page.
> *the file name doesn't have to be named `symp.toml` specifically, any file
> name with the .toml extension can be used (the `--config` option in the `symp`
> cli can be used to point to a non-default toml file).
Once you've created your `symp.toml` file, you can use the `symp` program to
add, remove, sync, and check the status of packages in your `symp.toml` file.
To add and sync all packages in your `symp.toml` file, run the below command
from within the directory containing your `symp.toml` file:
## Using the `symp` cli
```shell
symp add --all
```
When you run this command, a lock file called `symp.lock` will be created (if
your toml file has a different name, like `foo.toml`, then the lock file will be
named `foo.lock`). The lock file keeps track of the local sync state of packages
in your symp.toml file.
> Because these lock files are dependent on local system state, they generally
> should be ignored by version control systems like git. E.g. your `.gitignore`
> file (or similar) should include these files.
If you want to add/sync some of the packages, you can specify them in the
command:
```shell
symp add package1 package2 package3
```
You can add packages without automatically syncing by including the `--no-sync`
flag:
```shell
symp add --no-sync package1 package2 package3
```
This will only add the packages to the lock file; the symlinks for these
packages will not get created. If you later want to sync these packages, you
can run `symp sync`.
To remove packages, the `symp remove` command can be used. It supports the same
options as `symp add`.
To get an overview of the current status of all packages in your `symp.toml`
file, the `symp status` command can be used:
```shell
symp status --all
```
Like `symp add` and `symp remove`, you can also choose to display the status
of only a selection of packages:
```shell
symp status package1 package2 package3
```
As a final note, all four commands support the `--config <CONFIG>` option, which
can
be used to point to a `symp.toml` file located in another directory, or any
other toml file. If you supply a `$directory` to this option, then symp will
try to use the `symp.toml` file located at `$directory/symp.toml`. See below
for some examples of using this option:
```shell
# add packages from the symp.toml file located at $PWD/subdir/symp.toml
symp add --config subdir/symp.toml --all
# this command is the same as the one above, as a directory
# input to the --config option will use the file named `symp.toml`
# within that directory.
symp add --config subdir --all
# you can point to any toml file with the --config option, not just files
# named `symp.toml`
symp add --config symp-extras.toml --all
```
For a complete cli reference, you can either run `symp --help` or go to
the [cli reference](docs/cli.md) page (they both have the same contents).
## Potential 'gotchas' and philosophical notes
### How `symp` (doesn't) handle multiple `symp.toml` files
`symp` is truly a simple program. One of the ways in which it is simple is that
it does not have a global lock file. Instead, lock files are tied to their
corresponding `symp.toml` files, and are completely unaware of any other
`symp.toml` file or lock file on the system. This means that `symp` will
happily let you add a package from one `symp.toml` file, even if that package
conflicts with and overwrites the symlinks created by a package that was
added from a different `symp.toml` file.
I want to stress that _this is a feature_, albeit one with side effects if you
are unaware of the feature or have misconceptions about how `symp` operates.
The lack of a global lock file keeps the behavior of `symp` consistent and
intuitive to understand, which is something that I value more than the whatever
benefits having a global lock file can give (though I personally can't think of
any).
This isn't to dissuade you from creating and adding packages from multiple
symp.toml files. That's perfectly fine to do, just be aware of this
(non)-behavior by `symp`.
## (Potential) Future features
- [ ] `edit` command for editing symp.toml files? (not sure if I want this,
but could be fun to implement)
- add package
- remove link
- add link
- remove link
- update source/destination root
- update existing file policy
- etc.