paperboat
Sign in Install

The same dotfiles on every machine

A new server starts with none of your shell and editor settings. Point Paperboat at your dotfiles repository, say which files go where, and approve the change. 

$ pb config repository connect git@github.com:ana/dotfiles.git
$ pb config sync init
$ pb config sync validate --repository <repository-id>
$ pb config sync apply --repository <repository-id>
$ pb config status
  1. 1

    Any Git repository: HTTPS, SSH or a local path. It stays yours.

  2. 2

    Run on the machine you are configuring. Apply shows exactly what will change and asks you to confirm.

  3. 3

    What is in sync, what is pending, what conflicts.

The config file

Shared rules live in .paperboat/config-sync.toml. A machine's own file wins, then its [machine.<name>] section, then its OS, then the defaults.

mode = "pull_only" makes a machine follow the repository without pushing its edits back.

.paperboat/config-sync.toml
version = 1
mode = "pull_only"

[os.linux.paths."myapp/settings.json"]
local_path = "~/.config/myapp/settings.json"
kind = "file"

[os.darwin.paths."myapp/settings.json"]
local_path = "~/Library/Application Support/myapp/settings.json"
kind = "file"

# One machine that is different, said where everyone can see it.
[machine.build-server.paths."myapp/settings.json"]
local_path = "/srv/myapp/settings.json"

Conflicts

If a file changed on the machine and in the repository, Paperboat does not merge and does not pick a winner. It lists the path, shows both versions, and applies the side you keep.

The web console lists the same conflicts.

$ pb config conflict list studio
$ pb config conflict compare studio <path>
$ pb config conflict resolve studio <path> --keep repository
  1. 1

    Paths that changed on the machine and in the repository.

  2. 2

    Both versions, side by side.

  3. 3

    Or --keep machine. Nothing is overwritten until you choose.

Questions

Is my repository encrypted by Paperboat?

No. Synced files and their Git history are ordinary files in your repository, readable by whoever can read the repository. Keep secrets in ENV, not in tracked files.

Which files does it refuse to sync?

Credentials, .env files, SSH key material and Paperboat's own state are always excluded, whatever your rules say.

Does it guess where files go on each operating system?

No. You name each destination, per operating system if they differ. Paperboat never translates or infers a path.

How is this different from a dotfiles manager like chezmoi or stow?

Those are run by you on each machine. Config sync runs as part of Paperboat on machines you already manage with it, applies changes after you approve them, and shows conflicts for every machine in one place. If chezmoi already works for you, there is no need to switch.

Can a team share defaults?

Yes. A team sets a default repository, and members adopt or leave it per machine with pb config team-default-adopt and team-default-unadopt.

Start with the machine in front of you

Install Paperboat here, then on a second machine. Free for personal use, no card needed.

$ curl -fsSL https://get.pprbt.dev/install | bash
> irm https://get.pprbt.dev/install.ps1 | iex
View install script View install script