Git access

Every SetFork list is backed by a real git repository served over smart HTTP. Anything that speaks git — the CLI, VS Code, CI — can work with lists directly.

Clone

Public lists clone anonymously:

git clone https://setfork.com/{owner}/{slug}.git

Private lists and drafts require an API token as the password (any username):

git clone https://anything:sf_YOUR_TOKEN@setfork.com/you/private-list.git

What's inside

The repository contains list.json — the canonical representation of the list (title, description, tags, type, and blocks: steps, text, polls, quizzes and more). Each published version is one commit, so git log shows the version history and git diff shows what changed between versions.

Push

Pushing requires a token with write scope; you must be the owner or a collaborator.

# edit list.json, then:
git commit -am "tighten the rollback steps"
git push

A push to the default branch is projected back into the platform: it creates a new version of the list, exactly as if you had edited and published in the UI.

Branches and suggestions

Push a branch to propose changes without touching the main line:

git switch -c sharper-steps
git push -u origin sharper-steps

A branch can be turned into a suggestion (SetFork's pull request) and merged by the owner — including conflict resolution when the list moved on since your branch diverged. Branches, suggestion tabs and merging in the UI are covered in Collaboration.

Propose a change without opening a browser

A normal push creates a branch — a draft nobody has been shown. To propose the change right away, push to refs/for/main:

git switch -c sharper-steps
# edit list.json, commit
git push origin HEAD:refs/for/main

remote: SetFork: change accepted, the suggestion will appear on the list page

The suggestion shows up on the list page and the owner gets a notification. You do not need a draft branch for this: the commits land in your own branch inside the list.

Pushing to refs/for/main again is a new revision of the same suggestion, not a second one. Address the review, push again, and the discussion continues in place.

Hence one limit: you have one suggestion in flight per list at a time. Need a second? Push a normal branch and open the suggestion in the UI.

The trick will be familiar from Gerrit; main is the only supported base.

What the terminal can and cannot do

Everything that lives in git objects is available from the terminal. Everything around them is an add-on: it lives in the database, not in the repository, and works through the UI or the MCP server.

Recipes

Version history. Every version is a commit tagged vN:

git log --oneline --decorate     # what changed and when
git show v3                      # a whole version
git diff v3 v4 -- list.json      # what changed between versions

Check before pushing — the same things the server checks:

git ls-tree -r --name-only HEAD   # only README.md, list.json, .gitattributes
python -m json.tool list.json     # the canonical file must be valid JSON

CI. Cache the clone between runs: git endpoints are rate-limited per client IP, and an aggressive CI will hit the limit.

git clone --depth 1 https://anything:$SF_TOKEN@setfork.com/you/list.git

Limits

• HTTPS only. There is no SSH access: a token covers the same scenarios, including VS Code and CI.
• Exactly three files in the tree — README.md, list.json and .gitattributes. A push with anything else is refused and the extra path is named: list content lives in list.json, and README.md is generated from it.
• main is protected from deletion and history rewrites. Draft branches can be force-pushed freely.
• Pushing to a list is for the owner and collaborators. Outside contributions currently go through the UI or MCP.
• Size. There is a ceiling per push and per repository; text lists never come close, but large attachments do not belong there — images live separately.

Mirroring to an external forge

A list can be pushed automatically to a repository on GitHub or GitLab — as a shop window and a backup. Setup and tokens are covered in Mirror to GitHub/GitLab.