docs: move the branch warning into a TOOLING.md that main does not have
Putting it at the top of README.md worked, but it diverged a shared file: a probe showed main editing the adjacent line conflicts on every merge. The warning survived the conflict, so nothing was ever silently lost, but a file that only exists on this branch has no such cost at all. TOOLING.md carries the warning plus what CLAUDE.md would have said if it could — the commands, the remote policy, and the two guards, which are local and unversioned and so are absent from every fresh clone. Shared files are byte-identical to main again: CLAUDE.md, README.md and package.json. The divergence is now only files main has never had. Trade-off worth knowing: gitea renders README.md on the branch page and does not render TOOLING.md, so this warning is one click less visible than it was. The pre-push hook, not the documentation, remains the guard that actually stops a mistake. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UXfdJu7QhSJLr47K7koTDF
This commit is contained in:
Claude Opus 5
@@ -1,37 +1,5 @@
|
||||
# InstaArchive Viewer
|
||||
|
||||
> [!CAUTION]
|
||||
> ## This branch must not be published to GitHub
|
||||
>
|
||||
> You are on **`tooling`**. It is the only branch that still contains the
|
||||
> archive-fetching scripts and their docs, and those name things `main` was
|
||||
> rewritten to remove:
|
||||
>
|
||||
> - the fetch host's **public IP** (`docs/gallery-dl.md`)
|
||||
> - the browser profile the session cookie is read from
|
||||
> - the NAS archive path
|
||||
> - the **list of Instagram accounts being archived**
|
||||
>
|
||||
> On 2026-08-20 `main`'s entire history was rewritten with `git filter-repo`,
|
||||
> the GitHub repo was deleted and recreated, and 22 container images were
|
||||
> pruned from ghcr — all to remove exactly this material from public view.
|
||||
> **One push of this branch to GitHub undoes all of it**, and the second
|
||||
> cleanup would be harder than the first: force-push residue stayed reachable
|
||||
> by SHA until the repo itself was deleted.
|
||||
>
|
||||
> Guards in place, neither of them foolproof:
|
||||
>
|
||||
> - `.git/hooks/pre-push` rejects any ref but `main`/tags to the GitHub remote.
|
||||
> It is **local and unversioned** — a fresh clone does not have it.
|
||||
> - `git config remote.github.push refs/heads/main:refs/heads/main`.
|
||||
>
|
||||
> Recreate both after cloning. `origin` is gitea and is the right default for
|
||||
> everything; GitHub only ever needs `main` and the current release tag.
|
||||
>
|
||||
> *This block exists only on `tooling`. If a merge from `main` ever conflicts
|
||||
> here, keep both sides — the warning is not something `main` deleted.*
|
||||
|
||||
|
||||
A high-performance React PWA for browsing archived Instagram data with a native-feeling interface. Supports both official Instagram exports and Instaloader archives.
|
||||
|
||||
## Features
|
||||
|
||||
+94
@@ -0,0 +1,94 @@
|
||||
# Tooling branch
|
||||
|
||||
> [!CAUTION]
|
||||
> ## This branch must not be pushed to GitHub
|
||||
>
|
||||
> `tooling` is the only branch that still contains the archive-fetching
|
||||
> scripts and their docs, and those name things `main` was rewritten to
|
||||
> remove:
|
||||
>
|
||||
> - the fetch host's **public IP** (`docs/gallery-dl.md`)
|
||||
> - the browser profile the session cookie is read from
|
||||
> - the NAS archive path
|
||||
> - the **list of Instagram accounts being archived**
|
||||
>
|
||||
> On 2026-08-20 `main`'s entire history was rewritten with `git filter-repo`,
|
||||
> the GitHub repo was deleted and recreated, and 22 container images were
|
||||
> pruned from ghcr — all to get exactly this material out of public view.
|
||||
> **One push of this branch to GitHub undoes all of it.**
|
||||
>
|
||||
> A second cleanup would be harder than the first: after a force-push the old
|
||||
> commits stayed reachable by raw SHA, and only deleting the repository
|
||||
> outright removed them.
|
||||
|
||||
## Remotes
|
||||
|
||||
| remote | what goes there |
|
||||
|---|---|
|
||||
| `origin` → gitea | everything: `main`, `tooling`, tags, backups |
|
||||
| `github` | **`main` and the current release tag only** — it exists to run the CI/CD image build |
|
||||
|
||||
The other 22 release tags stay on gitea. Pushing them all to GitHub triggers
|
||||
one container build per tag, because each tag carries its own workflow file.
|
||||
|
||||
## Guards — recreate these after a fresh clone
|
||||
|
||||
Neither guard is versioned, so a new clone has **no protection at all**:
|
||||
|
||||
```sh
|
||||
git config remote.github.push refs/heads/main:refs/heads/main
|
||||
|
||||
cat > .git/hooks/pre-push <<'HOOK'
|
||||
#!/bin/sh
|
||||
remote_url="$2"
|
||||
case "$remote_url" in *github.com*) ;; *) exit 0 ;; esac
|
||||
while read -r _ _ remote_ref _; do
|
||||
[ -z "$remote_ref" ] && continue
|
||||
case "$remote_ref" in
|
||||
refs/heads/main|refs/tags/*) ;;
|
||||
*) echo "pre-push: refusing to push '$remote_ref' to GitHub." >&2; exit 1 ;;
|
||||
esac
|
||||
done
|
||||
exit 0
|
||||
HOOK
|
||||
chmod +x .git/hooks/pre-push
|
||||
```
|
||||
|
||||
Decide on the **remote** ref, not the local one: a delete push sends
|
||||
`(delete)` as the local ref, and an earlier version of this hook rejected
|
||||
every deletion because of it.
|
||||
|
||||
## What lives here
|
||||
|
||||
| path | what it is |
|
||||
|---|---|
|
||||
| `scripts/gdl-sync.py` | the gallery-dl fetcher; replaced JD2 for the ARTMS profiles |
|
||||
| `scripts/test_gdl_sync.py` | its tests |
|
||||
| `scripts/jd2-sync.ts` | JDownloader `.crawljob` generator, still used elsewhere |
|
||||
| `docs/gallery-dl.md` | the measurements behind every option in the fetcher — **read before changing pacing** |
|
||||
| `docs/jdownloader.md` | the older JD2 flow |
|
||||
| `docs/artms-instagram-accounts.txt` | the profile list passed to `--urls-file` |
|
||||
|
||||
## Commands
|
||||
|
||||
```sh
|
||||
# fetch: always --dry-run first; it prints the plan and the publish step
|
||||
./scripts/gdl-sync.py --index https://instaarchive.ergosteur.com \
|
||||
--staging <dir> --publish <user>@<nas>:<archives> \
|
||||
--archive-db <db> --urls-file artms_account_links.txt --abort 50 --dry-run
|
||||
|
||||
# crawljobs (no npm script — package.json is kept identical to main)
|
||||
npx tsx scripts/jd2-sync.ts --archives <dir> --dry-run
|
||||
```
|
||||
|
||||
Run the fetcher from the host whose public IP matches the browser the cookie
|
||||
came from. `--abort 50` is the routine setting; omit it for a full sweep that
|
||||
also catches edited carousels.
|
||||
|
||||
## Why there is no CLAUDE.md entry for any of this
|
||||
|
||||
`CLAUDE.md`, `README.md` and `package.json` are kept **byte-identical** to
|
||||
`main` so that merging `main` into `tooling` never conflicts. The earlier
|
||||
attempt put tooling notes in `CLAUDE.md` and a `jd2` script in `package.json`;
|
||||
because `main` had *deleted* those lines, every merge re-applied the deletion.
|
||||
Keep branch-specific documentation in this file, which `main` does not have.
|
||||
Reference in New Issue
Block a user