lnko

Simple stow-like dotfile linker.

Features

Conflict handling Interactive prompt with backup, skip, overwrite, and diff options when files already exist.	Orphan cleanup lnko clean removes stale symlinks pointing to non-existent targets.
Stow-compatible Works with existing GNU Stow symlinks. Supports tree folding for cleaner directory structures.	Relative symlinks Portable across machines. Symlinks use relative paths, not absolute.

Installation

Standalone binary (recommended)

Downloads a self-contained binary with no dependencies:

curl -fsSL https://raw.githubusercontent.com/pgagnidze/lnko/main/install.sh | bash

LuaRocks

Installs as a Lua module (requires Lua and LuaFileSystem):

luarocks --local install lnko

Usage

# Link packages from current directory to $HOME
lnko link bash git nvim

# Specify source and target directories
lnko link -d ~/dotfiles/config -t ~ bash git nvim

# Unlink packages
lnko unlink bash

# Show status of all packages
lnko status

# Remove orphan symlinks
lnko clean

Options

Option	Description
-d, --dir <dir>	Source directory containing packages (default: cwd)
-t, --target <dir>	Target directory (default: $HOME)
-n, --dry-run	Show what would be done
-v, --verbose	Show debug output
-b, --backup	Auto-backup conflicts to <target>/.lnko-backup/
-s, --skip	Auto-skip conflicts
-f, --force	Auto-overwrite conflicts (dangerous)
--ignore <pattern>	Ignore files matching pattern (can be repeated)

Conflict Handling

When lnko encounters existing files, it prompts for action:

• [b]ackup - Move existing file to .lnko-backup/
• [s]kip - Leave existing file, skip this link
• [o]verwrite - Replace existing file
• [d]iff - Show diff between source and target
• [q]uit - Abort operation

Use -b, -s, or -f flags to auto-resolve conflicts.

How It Works

lnko creates relative symlinks from a source directory (containing "packages") to a target directory. Each package is a directory whose contents mirror the target structure.

dotfiles/
  bash/
    .bashrc
    .bash_profile
  git/
    .gitconfig

Running lnko link -d dotfiles -t ~ bash git creates:

~/.bashrc -> ../dotfiles/bash/.bashrc
~/.bash_profile -> ../dotfiles/bash/.bash_profile
~/.gitconfig -> ../dotfiles/git/.gitconfig

Example

See pgagnidze/dotfiles for a real-world example using lnko.

Comparison with GNU Stow

Both use relative symlinks, tree folding, ignore patterns, and dry-run mode. lnko adds:

Feature	Description
Interactive conflicts	Prompt with backup, skip, overwrite, diff
Orphan cleanup	Find and remove broken symlinks
Status command	See state of all packages

See GNU Stow documentation for additional Stow features.

Development

# Run from source
./bin/lnko.lua --help

# Run linter
luacheck lnko/ bin/ spec/

# Run tests
busted spec/

License

GPL-3.0