Repository

The most primitive way for several people to work on code is zipping the folder and passing it around. Whoever made a change sends it, the recipient unpacks it and carries on. Working alone, that is enough: there is one copy, and it is the one on your machine.

Past two people, three problems arrive at once. Pagedeck passed server code around this way early on. Filenames ended up stacking a date, a person's name, and the word final, and nobody could say with certainty which one was running in production. Someone eventually diffed two of the zips to find out, which took an afternoon.

The second is that reasons do not survive. A conditional had appeared in the code a month earlier and nobody knew why it was there. Removing it felt likely to break something, so it sat untouched for six months.

The third is overwriting. Two people edit in the same week and hand their versions over in sequence; the later one erases the earlier one's work. The vanished code shows up as a feature that disappeared in the next release. Nobody notices at the moment of the overwrite, which is what makes it expensive.

Holding code and history in one space, and treating that space as the only reference, is what this concept is.

Code files and the record of how those files changed live in the same space. Four things are inside.

1. Every file as it stands right now.
2. Every commit — a point where a change was recorded as one unit, with a message saying what changed and why.
3. The list of branches, the work lines split off from the trunk. Who is building what, and where, is visible here.
4. Settings that apply to this space only: what stays out of history, whose approval is required before merging. These live in the repository rather than in someone's memory, which is the point.

What distinguishes it is that the whole thing gets copied. Git, the de facto standard, is distributed, so each person's machine holds not just files but the entire history, and you can search a record from six months ago with no network. The repository in the middle being authoritative is a team agreement rather than a technical constraint; each copy and that central one get pushed and pulled into alignment. It also means losing the central server is an inconvenience rather than a catastrophe, as long as somebody has a recent copy.

Where to draw the boundary has no fixed answer. Usually one product or one service takes one repository. Putting several projects into one space — a monorepo — is also done. Two questions decide it: does this ship together, and does one change have to edit both sides. If the web client and the server always release together and every API change touches both, keeping them apart is not buying much. Splitting later is easier than merging later, which is a mild argument for starting separate.

Some things must stay out. Access keys and passwords, once committed, remain in the history — delete them in the next commit and they are still visible by opening the earlier record. On a public repository, automated scanners find them within minutes of the push. Those values belong outside the code and get injected at run time, which is secret management. Large files also accumulate in history, so images and datasets are better kept outside the repository. Rewriting history to remove one is possible and unpleasant, and every collaborator has to re-sync afterward.

The largest use is as the unit of collaboration. Who can read, who can merge, and how many approvals a merge needs all attach to this space. Enforcing the rule in settings rather than asking people to remember it means nothing reaches the trunk unapproved.

The second is as the trigger for automation. CI/CD, which validates code changes automatically and carries them through to deployment, runs on new records arriving in this space. What gets tested and deployed is a specific state of the repository rather than a set of files somebody selected. Asked later what was deployed, you can answer by pointing at one commit, which is why a deployment gets described by a commit hash rather than a date.

The third is where documentation lives. The guide to running the code and the record of why it was designed this way sit next to the code. Kept in a separate document tool, they stop being updated when the code changes; kept in the same space, one change can carry both, and review covers the document alongside the code.

The fourth is publishing. Opening a repository does not by itself establish what anyone may do with the code. That requires an open source license, which sets the conditions of use. A public repository without one grants no rights at all in legal terms.

The fifth is new joiners. Looking at current code leaves a lot unexplained, and reading the message on the commit that introduced a line usually supplies the reason.

"Which repo is that code in?"

Asking where to go looking for the history.

"Let's decide whether to split or merge these repos. Right now every API change means deploying both."

The boundary and the deployment unit have come apart.

"A key got committed. It has to come out of history and the key has to be reissued."

Deleting it is not the end of the job.

At Pagedeck, repositories are split per service, while the web client and server that always ship together share one. Theo follows a fixed order when creating a new one: write the guide, list what stays out of history, block direct pushes to the trunk, and require one approval. Not doing those four at the start makes them hard to introduce later.

Treating a repository as file backup is common. Not losing code is the first benefit anyone notices. But storing files is something a cloud folder does too. What this space does is stack every change with an account of who made it and why, in order, so any point in that sequence can be returned to. Teams using it as backup end up writing "update" as every commit message, and then the history exists but cannot be read, which leaves no point worth returning to. History is useful only to the degree it was written for a reader.

The other is going to one extreme on boundaries. Putting everything in one space looks easier to manage; splitting finely looks independent. The test is deployment, not preference. Split things that always ship together and one feature needs two deployments in the right order; combine things that ship separately and one change reruns the other's checks every time.