114 lines
4.1 KiB
Markdown
114 lines
4.1 KiB
Markdown
# 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
|
|
```
|