From 458596f36c01906b9db38aaf45e5679f1b8dcae5 Mon Sep 17 00:00:00 2001
From: Pathfinder <pathfinder@ku-it.org>
Date: Tue, 27 Oct 2026 16:18:48 +0100
Subject: [PATCH] README: bare-repo dotfiles workflow (alias, sync, adding
 folders)

---
 README.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..94ba11d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,89 @@
+# fedora-dots — personal dot-files
+
+My user configuration, tracked with a **bare git repo** so files stay exactly
+where they are — nothing is copied, moved, or symlinked.
+
+Repo storage: `~/.cfg.git` (hidden) · Work tree: `$HOME` · Alias: `cfg`
+
+```
+laptop                                 Gitea                       VM / fresh install
+~/.cfg.git ──cfg push──► fedora-dots ◄──cfg pull── ~/.cfg.git
+     ▲                                                                    │
+     └────────────── your real files (~/.config/…) ◄──cfg checkout────────┘
+```
+
+## Current contents
+
+- `.config/niri/` — compositor config
+- `.config/noctalia/` — shell config (colors, plugins, settings)
+
+## The alias (required once per machine)
+
+```bash
+alias cfg='git --git-dir=$HOME/.cfg.git --work-tree=$HOME'
+```
+
+Put it in `~/.bashrc` (or your shell's equivalent) to make it permanent.
+
+## New machine setup (two ways)
+
+**Automatic** — the [fedora](https://git.ku-it.org/yuri/fedora) setup script
+asks *"Clone personal dotfiles?"* (or use `--dotfiles=yes`). It does a bare
+clone into `~/.cfg.git`, checks everything out into `$HOME`, and sets
+`status.showUntrackedFiles no`. Nothing manual needed.
+
+**Manual:**
+
+```bash
+git clone --bare gitea@git.ku-it.org:yuri/fedora-dots.git ~/.cfg.git   # --bare matters!
+cfg config status.showUntrackedFiles no
+cfg checkout
+```
+
+(`checkout` may need `-f` if stock files are in the way — that overwrites them
+with the repo versions, which is the point on a fresh machine.)
+
+## Daily workflow
+
+| What | Where | Commands |
+|---|---|---|
+| **Changed a tracked file** | the machine you edited it on | `cfg add <path>` → `cfg commit -m "…"` → `cfg push` |
+| **Sync latest onto another machine** | VM / other box | `cfg pull` |
+| **See what changed / is unsynced** | anywhere | `cfg status` |
+| **Take Gitea's version, discard local edits** | VM | `cfg checkout -f` (careful) |
+
+### Adding a new folder (opt-in, one at a time)
+
+```bash
+cfg add ~/.config/alacritty        # any path under $HOME
+cfg commit -m "alacritty"
+cfg push
+```
+
+Nothing is tracked until you name it. `status.showUntrackedFiles no` keeps
+`cfg status` quiet about everything else.
+
+### Good next candidates
+
+`~/.bashrc` · `~/.config/alacritty/` · `~/.config/fuzzel/` · `~/.gitconfig`
+(**strip credentials first** — a secret pushed is a secret exposed, private
+Gitea or not)
+
+## Rules of the road
+
+1. **Edit + push from the machine where you maintain it** (the laptop);
+   `cfg pull` on consumers.
+2. **Do NOT edit files through Gitea's web GUI** — that changes only the
+   server copy; your next push silently overwrites it. Web is for reading.
+3. **`cfg status` clean = everything synced.** Run it weekly; drift is the
+   only real risk of this setup.
+4. **Never track secrets**: tokens, passwords, `.netrc`, history exports.
+   Keep those out of git entirely.
+
+## Why bare + alias (instead of a normal repo or symlinks)
+
+- A normal clone would need its files *inside* the repo folder — but dot-files
+  must live in `$HOME`. The bare repo decouples storage from location.
+- No symlinks means no tooling surprises and no broken links; files are real
+  files in their real places.
+- It's plain git — no stow/chezmoi/yadm dependency to install on every machine.