nstow 0.2.1

[BROKEN] Cross-platform symlink farm manager with links defined in a stowfile
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# Nstow


> **BROKEN!**
>
> This crate is broken and may not be updated in the forseeable future.  
> Use at your own risk.

`nstow` is a symlink farm manager that aims to superset[^1] GNU Stow (or `stow`).

It is a clone of [`new-stow`](https://github.com/adam-gaia/new-stow) with cross-platform compatiblity.

[^1] See the comparison section below.

## Install


The package `nstow` provies a binary named `nstow`.

### Cargo


```bash
cargo install nstow
```

### Distro packages


TODO

## Usage


1. Create a stowfile (see Stowfiles section further down)
2. Link files

```bash
nstow --stow
```

3. Unlink files

```bash
nstow --unstow
```

### Examples


- Stow has historically been used to create symlinks from compiled execs to locations on the path.
  See `./examples/exec` for an example
- See `./examples/dotfiles` for an example on using `nstow` to manage dotfiles

### Additional information


`nstow --help`

## Stowfiles


`nstow` searches the working directory for a `stowfile`.
Stowfiles define a set of sources and links.

```yaml
---
vars:
  # Variables may be defined for use in a src or link path
  - THIS_IS_A_VAR=var_value
  # Additionally, environment variables are inherrited

stow:
  - src: some_example_file
    links:
      - ${HOME}/${THIS_IS_A_VAR}/link_it_here # One source file may be linked to many places
      - ${HOME}/some/nested/dir/link_it_here_too # Link's parent directories are created if they do not exist

  - src: alacritty.yml
    links:
      # Example of Stowfile using an env var not defined in the `var` section
      - "${XDG_CONFIG_HOME}/alacritty/alacritty.yaml"

  # Source files may be arbitrarily nested in directories
  - bash:
      - src: bashrc
        links:
          - "${HOME}/.bashrc"

      - src: bash_profile
        links:
          - "${HOME}/.bash_profile"

  # The source can have any name, even something unrelated to the link's name
  - src: readline
    links:
      - "${HOME}/.inputrc"
```

The stowfile above will result in links

- ./some_example_file -> ~/var_value/link_it_here
- ./some_example_file -> ~/some/nested/dir/link_it_here_too
- ./alacritty.yml -> ~/.config/alacritty/alacritty.yml
- ./bash/bashrc -> ~/.bashrc
- ./bash/bash_profile -> ~/.bash_profile
- ./readline -> ~/.inputrc

## Comparison between nstow and gstow

`nstow` aims to superset (most) of `stow`'s features [^2]

| GNU Stow Feature | New Stow | Comments |
| ---------------- | -------- | -------- |
| --no             | ✔        |          |
| --dir            | ✔        |
| --stow           | ✔        |
| --delete         | ✔        |
| --restow         | ✔        |
| --adopt          |          | planned  |
| --no-folding     |          | planned  |
| --ignore=REGEX   | ✔        |
| --defer=REGEX    |          |
| --override=REGEX | ✔        |
| --backup=REGEX   | ✔        |
| --dotfiles       |          | planned  |

Note that stow's regexes may match the beginning or end of a file while nstow regexes match any part.

TODO: do we want full feature parity with stow and the ability to link without a stowfile?
[^2]GNU Stow options are current with `2.3.1`, the latest at the time of writing.

## Developing

## Dependencies

Dependencies are managed with a [Nix Flake](https://nixos.wiki/wiki/Flakes). While we reccomend using Nix, you can ignore it and work with Cargo directly.
The `toolchain` list in `flake.nix` will specify any extra development dependencies.

## Testing

`./run-tests` runs the script `tests/integration-tests` in a container so that we can create/delete symlinks with impunity.