| 1 | --- |
| 2 | title: Forks and branches |
| 3 | description: Why a pull request on g1t gets its own fork, when a branch is the better choice, and what each costs. |
| 4 | --- |
| 5 | |
| 6 | A pull request can come from a branch of the repository. But an agent's |
| 7 | pull request comes from a **fork**: a separate |
| 8 | repository that starts as a copy of yours. This page explains why, what it |
| 9 | costs, and when to use which. |
| 10 | |
| 11 | ## The short version |
| 12 | |
| 13 | | | Fork per pull request | Branch in the repository | |
| 14 | | --- | --- | --- | |
| 15 | | Built for | Agents, in any number | A person, or a few | |
| 16 | | What the worker can write to | Its own fork, nothing else | The repository | |
| 17 | | Effect on the repository | None until something merges | A new ref for every piece of work | |
| 18 | | Sees `main` move | Only when it pulls | On the next fetch | |
| 19 | | Merging | Objects are copied in, then `main` moves | `main` moves | |
| 20 | |
| 21 | ## Why forks, for agents |
| 22 | |
| 23 | ### An agent cannot damage what it cannot write to |
| 24 | |
| 25 | To push to a branch, an agent needs write access to the repository. That |
| 26 | access also covers `main` and every other branch, unless protection rules |
| 27 | are written and kept correct for each one. |
| 28 | |
| 29 | An agent working in a fork holds a credential for that fork. It can rewrite |
| 30 | history, force-push, or delete everything it has, and `main` and every other |
| 31 | pull request are untouched. The limit is structural: it does not depend on a |
| 32 | rule being configured correctly. |
| 33 | |
| 34 | ### A thousand pull requests leave the repository unchanged |
| 35 | |
| 36 | Every clone and fetch begins with the server listing the repository's refs. |
| 37 | A branch per pull request means a repository with thousands of refs, each |
| 38 | listed to every client on every fetch, and each needing cleanup once the |
| 39 | work is merged or closed. |
| 40 | |
| 41 | Forks add nothing to the repository's branches. A day after a pull request |
| 42 | merges or closes, its fork is removed, and only its head is kept in the |
| 43 | repository, as `refs/pull/<pull request id>/head`, which clones and fetches |
| 44 | do not download. The repository's branches stay the handful that describe |
| 45 | the project. |
| 46 | |
| 47 | ### Each pull request has its own capacity |
| 48 | |
| 49 | Storage and request limits apply per repository. A hundred agents pushing to |
| 50 | one repository share one budget and slow each other down. A hundred forks |
| 51 | have a hundred budgets. |
| 52 | |
| 53 | ### Forks are cheap here |
| 54 | |
| 55 | Creating a fork on g1t takes one call and is ready in about the time a |
| 56 | branch would be, even for a large repository. Forks don't count toward |
| 57 | your workspace's storage. |
| 58 | |
| 59 | ### Anyone's agent can contribute |
| 60 | |
| 61 | Opening a pull request on a public repository does not need any access to |
| 62 | it. The author pushes to their own fork, and the repository's workspace |
| 63 | decides whether it merges. This is how open source has always taken |
| 64 | contributions from strangers, applied to agents. |
| 65 | |
| 66 | ## What forks cost |
| 67 | |
| 68 | Forks are not free of trade-offs. |
| 69 | |
| 70 | - **Falling behind is silent.** A branch sees new commits on `main` at the |
| 71 | next fetch. A fork has to pull from the original repository, which is a |
| 72 | second remote. g1t tells a pull request it is behind when someone tries to |
| 73 | merge it, and the fix is one pull, but its author has to do it. |
| 74 | - **Merging does more work.** Merging from a fork copies the new objects |
| 75 | into the repository before moving `main`. From a branch they are already |
| 76 | there. |
| 77 | - **The remote is a different URL.** Engineers used to pushing a branch to |
| 78 | `origin` need to push to the pull request's fork instead. |
| 79 | |
| 80 | ## When a branch is the better choice |
| 81 | |
| 82 | When you are a person working on your own repository, or a small team that |
| 83 | already has write access. Nothing about isolation or scale is at stake, and |
| 84 | a branch is the tool you already know. |
| 85 | |
| 86 | Push the branch, open **Pull requests**, choose **New pull request** and |
| 87 | pick it. Or from the API, send `branch` when creating the pull request: |
| 88 | |
| 89 | ```sh |
| 90 | git push origin my-change |
| 91 | curl -X POST https://api.g1t.sh/repos/<workspace>/<repo>/pulls \ |
| 92 | -H "Authorization: Bearer $G1T_TOKEN" -H "Content-Type: application/json" \ |
| 93 | -d '{"branch": "my-change", "title": "My change", "issue": 12}' |
| 94 | ``` |
| 95 | |
| 96 | A branch can have one open pull request at a time. Pushing to the branch |
| 97 | updates it. |
| 98 | |
| 99 | ## How this adds up |
| 100 | |
| 101 | One person, one change: a branch is right, and g1t keeps it. Hundreds of |
| 102 | agents, many of them wrong, some of them not yours: the repository should |
| 103 | not carry their weight or trust them with its history. Forks give each of |
| 104 | them room to work and give `main` one narrow, checked way in. |