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 --porcelain # `<code> <path>`, for scripts
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
store keeps nothing. A second checkout linking the same path is left with a
dangling symlink, there being only ever one stored copy.
store keeps nothing. Every checkout has a store directory of its own, so a
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:
```
$ 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
shadowed: config.local.py
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.
The store lives under
`${XDG_DATA_HOME:-$HOME/.local/share}/ahab/<host>/<owner>/<repo>/`, derived
from the Git `origin` remote, or `_local/<checkout>` when there is no remote to
name it after. 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.
`${XDG_DATA_HOME:-$HOME/.local/share}/ahab/<host>/<owner>/<repo>/<dir>-<hash>/`.
The repository part is derived from the Git `origin` remote, or
`_local/<checkout>` when there is no remote to name it after; the last part is
the checkout's directory name and a short hash of its full path, so two clones
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
@@ -145,7 +162,7 @@ postgres: db (postgres:18-alpine)
container: 189d4d395d62
user: myproject
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
`ahab link check` lists what a sandbox can still read
```