julien/apf_portal
1
0
Fork 0
Code Issues 1 Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(setup): version aliases.zsh + gitconfig.txt under docs/setup/dotfiles #224

Merged
julien merged 1 commits from docs/setup-versioned-dotfile-templates into main 2026-05-24 21:23:25 +02:00
Conversation 0 Commits 1 Files Changed 5
+96 -8
julien commented 2026-05-24 21:23:10 +02:00
Owner
Copy Link
Copy Source

Summary

Follow-up on #220. 80-dotfiles.sh was reading notes/aliases.zsh and notes/gitconfig.txt — but notes/ is the project lead's personal scratchpad and is gitignored, so a fresh clone on the dev VM has nothing to read:

✗ /home/APF/dev-jugautier/Works/apf_portal/notes/aliases.zsh not found.

Move both templates to a versioned location and update the script + docs to match.

What lands

File Change
docs/setup/dotfiles/aliases.zsh New. Project-wide zsh aliases (navigation / files / search / git / dev), previously living in notes/aliases.zsh. Header explains scope (project-wide, all devs pick it up on next zsh restart) and where per-dev customizations go (private dotfiles repo).
docs/setup/dotfiles/gitconfig.txt New. Base ~/.gitconfig template — init / core / aliases / colour. [user] block carries placeholder identity (name = your name / email = your.email@example.com) that the script overwrites at install via git config --global user.{name,email}.
docs/setup/scripts/80-dotfiles.sh Source paths flipped from $REPO_ROOT/notes/… to $REPO_ROOT/docs/setup/dotfiles/…. Header doc-comment updated.
docs/setup/01-dev-debian-vm-setup.md Step-3 table row and §8.4 (dotfiles repo) reference the new path. The §8.4 wording is also tightened — the script no longer "falls back" anywhere, it has one source of truth.
docs/setup/README.md New dotfiles/ section in the folder index. Step-7 row in the scripts table also reflects the new paths.

Why this lives in docs/setup/dotfiles/ and not infra/ or a top-level dotfiles/

  • The directory is consumed exclusively by 80-dotfiles.sh — co-locating it under docs/setup/ keeps the setup family self-contained (one folder to read, one folder to clone).
  • The name dotfiles/ reads correctly for a future per-dev dotfiles repo migration (§8.4) — the templates here become the seed of that repo, and the install script will then check ~/.dotfiles/ first and fall back to docs/setup/dotfiles/ second.

Unblock path (if you're stuck mid-bootstrap)

Either pull this PR, or manually create the two files at the new location on the VM:

mkdir -p ~/Works/apf_portal/docs/setup/dotfiles
# paste the aliases.zsh + gitconfig.txt content there
./docs/setup/scripts/80-dotfiles.sh

Test plan

  • On a fresh Trixie VM, ./docs/setup/scripts/80-dotfiles.sh succeeds: aliases.zsh symlink lands at ~/.oh-my-zsh/custom/aliases.zsh pointing at docs/setup/dotfiles/aliases.zsh, ~/.gitconfig written with the prompted identity.
  • Re-running the script reports ↪ skip aliases.zsh symlink already correct (idempotency).
  • git config --global user.name returns the prompted value (i.e. placeholder your name is overwritten).
  • pnpm exec prettier --check clean on the touched files.
  • bash -n docs/setup/scripts/80-dotfiles.sh clean.

Notes

  • notes/aliases.zsh and notes/gitconfig.txt on existing dev workstations are unaffected — those files live outside the repo (gitignored), nothing here touches them. They can be deleted or kept as personal scratch at the dev's discretion.
  • A future PR creates the private dotfiles repo (apf/dotfiles) and teaches 80-dotfiles.sh to prefer ~/.dotfiles/ over docs/setup/dotfiles/ when both exist.
## Summary Follow-up on [#220](https://git.unespace.com/julien/apf_portal/pulls/220). [`80-dotfiles.sh`](docs/setup/scripts/80-dotfiles.sh) was reading `notes/aliases.zsh` and `notes/gitconfig.txt` — but `notes/` is the project lead's personal scratchpad and is gitignored, so a fresh clone on the dev VM has nothing to read: ``` ✗ /home/APF/dev-jugautier/Works/apf_portal/notes/aliases.zsh not found. ``` Move both templates to a versioned location and update the script + docs to match. ## What lands | File | Change | | --- | --- | | `docs/setup/dotfiles/aliases.zsh` | **New.** Project-wide zsh aliases (navigation / files / search / git / dev), previously living in `notes/aliases.zsh`. Header explains scope (project-wide, all devs pick it up on next zsh restart) and where per-dev customizations go (private dotfiles repo). | | `docs/setup/dotfiles/gitconfig.txt` | **New.** Base `~/.gitconfig` template — init / core / aliases / colour. `[user]` block carries placeholder identity (`name = your name` / `email = your.email@example.com`) that the script overwrites at install via `git config --global user.{name,email}`. | | `docs/setup/scripts/80-dotfiles.sh` | Source paths flipped from `$REPO_ROOT/notes/…` to `$REPO_ROOT/docs/setup/dotfiles/…`. Header doc-comment updated. | | `docs/setup/01-dev-debian-vm-setup.md` | Step-3 table row and §8.4 (dotfiles repo) reference the new path. The §8.4 wording is also tightened — the script no longer "falls back" anywhere, it has one source of truth. | | `docs/setup/README.md` | New `dotfiles/` section in the folder index. Step-7 row in the scripts table also reflects the new paths. | ## Why this lives in `docs/setup/dotfiles/` and not `infra/` or a top-level `dotfiles/` - The directory is **consumed exclusively by [`80-dotfiles.sh`](docs/setup/scripts/80-dotfiles.sh)** — co-locating it under `docs/setup/` keeps the setup family self-contained (one folder to read, one folder to clone). - The name `dotfiles/` reads correctly for a future per-dev dotfiles repo migration (§8.4) — the templates here become the seed of that repo, and the install script will then check `~/.dotfiles/` first and fall back to `docs/setup/dotfiles/` second. ## Unblock path (if you're stuck mid-bootstrap) Either pull this PR, or manually create the two files at the **new** location on the VM: ```bash mkdir -p ~/Works/apf_portal/docs/setup/dotfiles # paste the aliases.zsh + gitconfig.txt content there ./docs/setup/scripts/80-dotfiles.sh ``` ## Test plan - [ ] On a fresh Trixie VM, `./docs/setup/scripts/80-dotfiles.sh` succeeds: aliases.zsh symlink lands at `~/.oh-my-zsh/custom/aliases.zsh` pointing at `docs/setup/dotfiles/aliases.zsh`, `~/.gitconfig` written with the prompted identity. - [ ] Re-running the script reports `↪ skip aliases.zsh symlink already correct` (idempotency). - [ ] `git config --global user.name` returns the prompted value (i.e. placeholder `your name` is overwritten). - [x] `pnpm exec prettier --check` clean on the touched files. - [x] `bash -n docs/setup/scripts/80-dotfiles.sh` clean. ## Notes - `notes/aliases.zsh` and `notes/gitconfig.txt` on existing dev workstations are unaffected — those files live outside the repo (gitignored), nothing here touches them. They can be deleted or kept as personal scratch at the dev's discretion. - A future PR creates the **private dotfiles repo** (`apf/dotfiles`) and teaches `80-dotfiles.sh` to prefer `~/.dotfiles/` over `docs/setup/dotfiles/` when both exist.
julien added 1 commit 2026-05-24 21:23:11 +02:00
docs(setup): version aliases.zsh + gitconfig.txt under docs/setup/dotfiles
CI / commits (pull_request) Successful in 3m53s
Details
CI / scan (pull_request) Successful in 4m0s
Details
CI / check (pull_request) Successful in 4m16s
Details
CI / a11y (pull_request) Successful in 3m25s
Details
Docs site / build (pull_request) Successful in 3m31s
Details
CI / perf (pull_request) Successful in 6m51s
Details
43c54616d8 
80-dotfiles.sh was reading notes/aliases.zsh and notes/gitconfig.txt,
but notes/ is gitignored - fresh clones on the dev VM hit "file not
found" and the script aborted.

Move both templates to docs/setup/dotfiles/ where they ship with every
clone. gitconfig.txt's [user] block now carries placeholder identity
(your name / your.email@example.com) instead of the original author's
identity - the script overlays the prompted values at install time so
the file content doesn't matter functionally, but the placeholders
read more clearly as "fill me in".

80-dotfiles.sh source paths flipped from $REPO_ROOT/notes/... to
$REPO_ROOT/docs/setup/dotfiles/.... Step-3 table row, §8.4 (dotfiles
repo appendix), and the setup README index updated accordingly. New
"dotfiles/" section in the setup README documents the folder.

The notes/aliases.zsh and notes/gitconfig.txt on existing dev
workstations are unaffected - those files live outside the repo and
this PR doesn't touch them.
julien merged commit 72e1182308 into main 2026-05-24 21:23:25 +02:00
julien deleted branch docs/setup-versioned-dotfile-templates 2026-05-24 21:23:29 +02:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adastra-bot (AdAstra Bot) julien (Julien Gautier)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: julien/apf_portal#224
Delete Branch "docs/setup-versioned-dotfile-templates"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?