symp

symp (short for symlink packages) 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 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 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 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

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:

symp add package1 package2 package3

You can add packages without automatically syncing by including the --no-sync flag:

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:

symp status --all

Like symp add and symp remove, you can also choose to display the status of only a selection of packages:

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:

# 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 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/target root
  • update existing file policy
  • etc.