================================================================================
 dotfiles
================================================================================

Personal shell + tooling configuration, scoped for use as a GitHub Codespaces
dotfiles repo. this branch assumes Linux (Ubuntu/Debian, the Codespaces base image).

--------------------------------------------------------------------------------
 What's here
--------------------------------------------------------------------------------

  .zshenv                       Login env, XDG paths, PATH seeds
  .my.cnf                       mysqldump column-statistics fix
  setup.sh                      Bootstrap entry point (run by Codespaces).
                                Clones the bare repo, checks out files into
                                $HOME, then installs apt essentials + delta
                                so the first shell works out of the box.
  .config/
    zsh/                        zshrc, aliases, themes, OMZ plugin list
    fish/                       config.fish, conf.d/, functions/
    git/                        config + global ignore
    vim/vimrc                   Minimal vim config
    gem/gemrc                   Ruby gem config

--------------------------------------------------------------------------------
 How Codespaces uses this
--------------------------------------------------------------------------------

GitHub clones this repo into every Codespace and runs `setup.sh`. That script:

  1. Clones the repo as a bare repo at $HOME/.cfg
     (https://www.atlassian.com/git/tutorials/dotfiles)
  2. Checks out the working tree into $HOME, backing up any conflicts to
     $HOME/.config-backup/.
  3. Sets `status.showUntrackedFiles=no` so $HOME isn't a sea of untracked.
  4. Installs apt essentials so the first shell works:
       eza, bat, fd-find, ripgrep, fzf, git-flow, pwgen, vim, plus
       git-delta from GitHub releases.

Heavier / non-apt tools (oh-my-zsh, mise, fisher, claude, codex, qsv, fish
plugins) are NOT installed automatically — Codespaces has a tight dotfiles
install timeout.

>>> Once the Codespace / devcontainer finishes provisioning, open a terminal
>>> and run `dotfiles_bootstrap` to install the rest. Each step is idempotent,
>>> so it's safe to re-run any time.

    exec zsh                  # or: exec fish
    dotfiles_bootstrap

`dotfiles_bootstrap` also runs `setup_git_identity`, which (in Codespaces only)
optionally prompts to write `~/.config/git/config.local` from
`$GIT_AUTHOR_NAME` / `$GIT_AUTHOR_EMAIL`. Skip the prompt to keep the
auto-configured Codespaces identity.

--------------------------------------------------------------------------------
 Per-machine git identity
--------------------------------------------------------------------------------

The tracked git config sets `useConfigOnly = true` and does NOT include a
name/email — every clone supplies its own via an included local file:

    # ~/.config/git/config.local
    [user]
        name = Your Name
        email = you@example.com

In Codespaces, identity is set automatically via `$GIT_AUTHOR_NAME` /
`$GIT_AUTHOR_EMAIL` env vars from your GitHub account, so a `config.local`
file is usually unnecessary. Run `setup_git_identity` (or
`dotfiles_bootstrap`) inside a Codespace to generate one anyway — useful for
tools that read `git config` directly rather than honoring the env vars.

--------------------------------------------------------------------------------
 Manual install (outside Codespaces)
--------------------------------------------------------------------------------

    DOTFILES_REPOSITORY="git@github.com:youruser/dotfiles.git" sh setup.sh

To skip the apt install step (e.g. on a non-Debian system or in a sandbox):

    DOTFILES_SKIP_INSTALL=1 sh setup.sh

--------------------------------------------------------------------------------
 Codespaces secrets used
--------------------------------------------------------------------------------

  TAILSCALE_AUTHKEY    Optional. Picked up by the ts-up helper to bring
                       Tailscale up with --ssh enabled (the official
                       tailscale codespaces feature does not pass --ssh).

--------------------------------------------------------------------------------
 Useful aliases / functions
--------------------------------------------------------------------------------

  config           git wrapper for the bare dotfiles repo
                   (e.g. `config status`, `config commit ...`)
  fe / fzp         fzf + fd file pickers (open / preview)
  rge / rgf        fzf + ripgrep search pickers
  ts-up/ip/status  Tailscale helpers (Codespaces)
  l, ll, la        eza listings
  cat              bat (with batcat fallback)

--------------------------------------------------------------------------------
 License
--------------------------------------------------------------------------------

GNU Affero General Public License v3.0 — see LICENSE.