Tapes

An atomic dotfile switcher for Linux and ricing. Swap your whole setup in one command and get it back in one command.

Rewritten to be safer, simpler and truly atomic

Report Bug · Request Feature · Join the Discord

Tapes has a Official GUI now, Check it out here, https://github.com/LilaccFlowerr/tapes-deck

If you like the project, Mind giving it a star 🌟?

Tapes in Action

https://github.com/user-attachments/assets/6791a91b-a3be-429b-9fd0-adc34fc93b08

Quickstart

Either package a ~/.config as a tape (put in it a folder, move to ~/.tapes and add a tape.toml inside), or install one directly from a repo. Then, you can easily insert the tape to try it out and eject it just as easily to return back to your old ~/.config.

# You found a cyberpunk dotfiles in a public repo
tapes install https://github.com/some_user/cyberpunk --name cyberpunk 
# if its in a specific branch or subdir in the repo, utilize the --branch and --dir subcommands

# Insert a tape sitting in ~/.tapes
tapes insert cyberpunk # tapes expects the tape in ~/.tapes/cyberpunk

# Wanna see its properties and hooks before insertion?
tapes show cyberpunk

# List all the tapes in ~/tapes
tapes show

# Is a tape currently inserted?
tapes status

# Wanna go back to your old config?
tapes eject

It's as simple as that! A tape.toml is meant to look like this:

[tape]
name = "cyberpunk" # required
desc = "A cool cyberpunk rice"
dependencies = ["hyprland", "quickshell"] # just useful data for the user, tapes does nothing with it as of now

[hooks]
insert = [
  "hyprctl reload",
  "qs kill",
  "waybar &",   "notify-send 'Tapes' 'Switched to cyberpunk rice'"
]

eject = [
  "hyprctl reload",
  "pkill waybar",
  # Tapes runs commands in the current shell session, so try to move them to the background
  "qs -c caelestia -d",  
  "notify-send 'Tapes' 'Back to caelestia'",
]

# install = [] # exists btw

Tapes expects the directory tree to look like this:

cyberpunk/
├── tape.toml         
├── hypr/             
│   └── hyprland.conf
├── waybar/           
│   └── config.jsonc
└── nvim/            
    └── init.lua

Some handy flags for tapes:

--dry-run # shows the plan without touching any files
--no-hooks # skip running any hooks
-p, --path # insert a tape straight out any folder
-q, --quiet # quiet output
-v, --verbose # verbose output
-l, --logging # show logs, useful for reporting issues and debugging

-V, --version # display the current version

Installation

Install script (grabs the latest release, re-run it to update)

curl -fsSL https://raw.githubusercontent.com/futurekismo-oss/tapes/main/install.sh | bash

Run tapes --version to ensure it worked. Make sure to add ~/.local/bin to your $PATH.

Cargo

cargo install [email protected]
cargo binstall [email protected] # prebuilt binary instead of compiling

Try to add ~/.cargo/bin to your $PATH if tapes --version doesn't work

Nix

nix run github:futurekismo-oss/tapes
nix profile install github:futurekismo-oss/tapes

From source

git clone https://github.com/futurekismo-oss/tapes
cd tapes
cargo install --path .

Tapes supports tab completion. Just add source <(COMPLETIONS=zsh tapes) to your shell init (.zshrc, or .bashrc). Replace zsh with your chosen shell. It supports zsh, fish, bash, elvish and nushell

Tip: If you find the name tapes annoying you can alias it to tapes, the binary can't be renamed tapes as it's taken on crates.io

Global Configuration

Tapes supports an optional global configuration file located at ~/.local/share/tapes/config.toml.

Generate a starter configuration with:

tapes config init

Helpful management subcommands:

tapes config path   # Show location of active config file
tapes config show   # Display current effective configuration

# Default tape when running `tapes insert` without arguments
# default_tape = "my-default"

[install]
shallow_clone = true              # Use --depth 1 for git clones by default
backup_on_force = true            # Backup existing tape to .bak on --force reinstall

# Custom Git provider shorthands (e.g. `tapes install lab:user/rice`)
[install.providers]
lab = "https://git.myserver.com/"

[hooks.global]
# Lifecycle hooks executed across ALL tapes
post_insert = [
    "notify-send 'Tapes' 'Switched tape to $TAPE_NAME'"
]
post_eject = [
    "notify-send 'Tapes' 'Restored base configuration'"
]

[targets]
# Files or folders in a tape that should never be symlinked into ~/.config
ignore = ["wallpapers", "assets", "scripts", ".DS_Store"]

Why Use Tapes?

If you're like me and a big unixporn fan, you've definitely found yourself wanting to try new rices, however the worry of trashing your old config holds you back. Install scripts barely care; they frequently override previous configs or just backup the entire config folder and make a new one, forcing you go to back and manually move files to fix the mess.

Tapes aims to solve this by making trying out new rices and reverting back to your old config as frictionless as possible as while being safe and fast. Other dotfile managers have come close, but don't really give this feeling of pop in a config and pop it out as fast (this is where the name came from). The initial implementation (v1) was hasty and buggy. It was a prototype.

Now, let's explain the terms you'll come across while using this program.

Tape: A tape is ~/.config folder, a rice, a dotfile; whatever you choose to call it. It contains folders like quickshell and hypr. Tapes can take this config folder and swap its targets or folders with your own, allowing you to use the example quickshell and hypr config in this tape as your config without losing things like chromium keys (which are stored in ~/.config/chromium for some reason).

Target: A target is a folder in a tape, a quickshell folder, or hypr folder, but a target can also be a file e.g .zshrc, starship.toml. These targets tell tapes the config you wanna insert into your ~/.config folder.

Atomic: You've heard me say it a lot. It means there is no in-between; when tapes insert a tapes, it takes the targets from your ~/.config folder, asks the tape which config it provides, and then builds an entire valid config folder called ~/.config.tapes made up of symlinks from the tape and your previous config. It then uses the renameat linux syscall to swap your ~/.config with ~/.config.tapes (meaning your old config becomes ~/.config.tapes and vice versa), and as there is no in-between state where your config is missing, it can call itself atomic, since anything before the swap can be easily rolled back by deleting ~/.config.tapes.

Hooks: Shell commands in the tape.toml. Tapes can run them after insert, after eject or after install. Make sure to read these if a repo provides its own tape.toml, even though it shouldn't.

FAQ

tapes install https://github.com/some_user/cyberpunk --name cyberpunk 
tapes insert cyberpunk

tapes install ~/cyberpunk --name cyberpunk
tapes insert cyberpunk

tapes eject
tapes install https://github.com/some_user/cyberpunk --name cyberpunk --force

Acknowledgements

Thanks to these wonderful individuals for

erotic-erox for calling out some lifecycle bugs on version 0.1.2-beta

LilaccFlowerr for providing the tapes showcase video and a GUI

saksham_kumar for being a contributor and writing the beloved install command

Mvk for providing lots of encouragement and support

Clover for providing the most encouragement and support, He encouraged the rewrite of tapes turning it from a broken mess to an actual usable utility

Marv for encouraging me to build tapes after i pitched the initial idea, without him, tapes would still be a random afternoon thought

Roadmap

• A GUI - https://github.com/LilaccFlowerr/tapes-deck
• Colored output
• Dependencies checking

Contributing

Contributions are welcome. See Contributing.md for the guidelines.

License

Distributed under the MIT License.

Stonks 📈