dotfiles v1.0.2

2026-06-19 19:56:26 +00:00
parent f6757cb4c6
commit 9ab72703ad
4 changed files with 358 additions and 9 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,113 @@
+# Dotfiles Manager
+
+A self-managing Fish shell configuration that tracks its own version, can
+automatically update itself from a Git repository, and manages standard
+dotfiles (`~/.tmux.conf`, `~/.gitconfig`, etc.) from version-controlled
+templates.
+
+## Quick Install
+
+```fish
+curl -fsSL https://git.toomuchtaco.net/taco/dots/raw/branch/main/install.fish | fish
+```
+
+This one-liner clones the repository, installs everything to
+`~/.config/fish/`, creates `~/.tmux.conf` and other dotfiles from templates,
+and prints next steps.
+
+**Prerequisites:** Fish shell 3.2+, Git.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `dotfiles help` | Show all subcommands |
+| `dotfiles version` | Display current version, repo URL, shell info |
+| `dotfiles status [name ...]` | Checksum-compare installed files against templates |
+| `dotfiles init [name ...]` | Create dotfiles from templates (backs up existing) |
+| `dotfiles update [name ...]` | Re-apply template contents (backs up existing) |
+| `dotfiles edit <name>` | Open `~/.<name>` in `$EDITOR` |
+| `dotfiles repo [url]` | Show or set the remote Git repository URL |
+| `dotfiles sync` | Pull latest templates from remote and re-apply |
+| `dotfiles publish` | Bump version, commit local changes, push to remote |
+
+### Examples
+
+```fish
+dotfiles status                # Check every managed file
+dotfiles init gitconfig        # Create only ~/.gitconfig
+dotfiles edit tmux             # Open ~/.tmux.conf in your editor
+dotfiles repo                  # Show current remote URL
+dotfiles sync                  # Pull updates and re-apply
+dotfiles publish               # Bump version, commit, push
+```
+
+## File Structure
+
+```
+~/.config/fish/
+├── config.fish              Main entry point — version, PATH, interactive setup
+├── install.fish             Bootstrap/install script (also at repo root)
+├── README.md                This file
+├── conf.d/
+│   └── aliases.fish         Example: Git abbreviations, helper functions
+├── functions/
+│   ├── dotfiles.fish        The `dotfiles` command and all subcommands
+│   └── gitea_key.fish       Helper: generate SSH key for Gitea
+└── dotfiles/
+    ├── tmux.conf            Template → ~/.tmux.conf
+    ├── gitconfig            Template → ~/.gitconfig
+    └── config/
+        └── starship.toml    Template → ~/.config/starship.toml
+```
+
+## How It Works
+
+### Versioning
+
+A single `DOTFILES_VERSION` variable at the top of `config.fish` is the
+source of truth.  When you run `dotfiles publish`, you are prompted for a
+new version (auto-suggested minor bump, or custom), and both the local
+`config.fish` and the remote repository are updated.
+
+### Templates
+
+Each file in `~/.config/fish/dotfiles/` is a template.  When you run
+`dotfiles init`, templates are copied to `~/` with a leading dot prepended
+(e.g. `tmux.conf` → `~/.tmux.conf`).  Templates in subdirectories are
+placed under `~/` preserving the path (e.g. `config/starship.toml` →
+`~/.config/starship.toml`).
+
+To add a new dotfile, simply drop a template file into `dotfiles/` and run
+`dotfiles init <name>`.  No registration needed.
+
+### Sync & Publish
+
+- **`dotfiles sync`** — clones the remote repo (shallow) and copies templates
+  into `dotfiles/`, then re-applies them.  Pulls changes *down*.
+- **`dotfiles publish`** — clones the remote repo (full), copies your local
+  `config.fish`, `functions/`, `dotfiles/`, and `conf.d/` into the clone,
+  prompts for a version bump, commits, and pushes.  Sends changes *up*.
+
+## Extending
+
+- **Add a template:** create a file in `~/.config/fish/dotfiles/`.
+- **Add shell config:** create a file in `~/.config/fish/conf.d/` (auto-sourced
+  by Fish in alphabetical order).
+- **Add a function:** create a file in `~/.config/fish/functions/` (auto-loaded
+  by Fish when first called).
+
+## Custom Install
+
+Pass a different repository URL to the install script:
+
+```fish
+curl -fsSL https://git.toomuchtaco.net/taco/dots/raw/branch/main/install.fish | fish -s -- https://github.com/you/your-dotfiles
+```
+
+Or clone manually and run the install script locally:
+
+```fish
+git clone git@gitssh.toomuchtaco.net:taco/dots.git /tmp/dots
+fish /tmp/dots/install.fish
+```