janezicmatej/ahab
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: the store is keyed by checkout, and how to migrate

Browse Source
This commit is contained in:
Matej Janezic
2026-09-21 13:07:56 +00:00
parent a6a4b033a7
commit a10e6b17b0
1 changed files with 26 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
README.md
View File

@@ -89,17 +89,19 @@ ahab link list # what the store holds for this repository
ahab link check # what a sandbox can still read ahab link check # what a sandbox can still read
ahab link check --porcelain # `<code> <path>`, for scripts ahab link check --porcelain # `<code> <path>`, for scripts
ahab link check --exit-code # exit 4 when anything is outside the store ahab link check --exit-code # exit 4 when anything is outside the store
ahab link migrate # move out of the layout ahab 0.5 used
``` ```
Restoring is the inverse of adding: the file comes back to where it was and the Restoring is the inverse of adding: the file comes back to where it was and the
store keeps nothing. A second checkout linking the same path is left with a store keeps nothing. Every checkout has a store directory of its own, so a
dangling symlink, there being only ever one stored copy. second clone of the same repository links and restores its files without
touching the first one's.
Every stored path is in one of three states: Every stored path is in one of three states:
``` ```
$ ahab link list $ ahab link list
store: /home/you/.local/share/ahab/git.aflabs.org/urnik/afurnik store: /home/you/.local/share/ahab/git.aflabs.org/urnik/afurnik/afurnik-5f1c8e3a
linked: .env linked: .env
shadowed: config.local.py shadowed: config.local.py
missing: secrets/token missing: secrets/token
@@ -124,11 +126,26 @@ entries end with a NUL, and the two paths of a symlink leading elsewhere are
separated by one as well, the way `git status -z` reports a rename. separated by one as well, the way `git status -z` reports a rename.
The store lives under The store lives under
`${XDG_DATA_HOME:-$HOME/.local/share}/ahab/<host>/<owner>/<repo>/`, derived `${XDG_DATA_HOME:-$HOME/.local/share}/ahab/<host>/<owner>/<repo>/<dir>-<hash>/`.
from the Git `origin` remote, or `_local/<checkout>` when there is no remote to The repository part is derived from the Git `origin` remote, or
name it after. Its directories are created `0700`. A remote or checkout name `_local/<checkout>` when there is no remote to name it after; the last part is
that needed characters replacing carries a short fingerprint of the original, the checkout's directory name and a short hash of its full path, so two clones
so two of them cannot share a directory. of one repository never share a directory. Its directories are created `0700`.
A remote or checkout name that needed characters replacing carries a short
fingerprint of the original, so two of them cannot share a directory either.
Moving a checkout changes its hash. The symlinks still resolve, `check` still
counts them as in the store and `restore <path>` still brings them back, so the
way over is `restore` followed by `add`; `list` and `restore --all` only look
in the new directory.
### Upgrading from 0.5
Before 0.6 the store had no per-checkout part, so existing links point at
`<repo>/` directly. They keep working. `list` and `status` report them as
`legacy`, and `ahab link migrate` moves them into the checkout's own directory
and repoints the links. Only what the current checkout links is moved, so
another clone's files in the same directory are left where they are.
## What ahab makes of your project ## What ahab makes of your project
@@ -145,7 +162,7 @@ postgres: db (postgres:18-alpine)
container: 189d4d395d62 container: 189d4d395d62
user: myproject user: myproject
database: myproject_db database: myproject_db
store: /home/you/.local/share/ahab/git.aflabs.org/urnik/afurnik store: /home/you/.local/share/ahab/git.aflabs.org/urnik/afurnik/afurnik-5f1c8e3a
linked: 2 linked: 2
`ahab link check` lists what a sandbox can still read `ahab link check` lists what a sandbox can still read
``` ```