{"canonical_url":"https://engineer.company/glossary/repository/","content_markdown":"# Repository\n\n## What it is\n\nA repository, nearly always shortened to repo in conversation, is where a\nversion control system keeps the full record of a project: every recorded state\nof every file, who made each change and why, and the names that lead into that\nhistory. The working files you edit are one view of it; the repository is\neverything behind that view.\n\nGit defines the word in its own glossary with some precision: “A collection of\nrefs together with an object database containing all objects which are reachable\nfrom the refs”. Both halves are worth unpacking. The object database holds the\ncontent. Each version of a file, each directory listing and each commit is\nstored as an object and named by a hash of its contents, which the Git book\ndescribes as a content-addressable filesystem: a key-value store where the key\nis computed from the value. Two identical files are one object, and any change,\nhowever small, produces a new name. The refs are the human side: branches and\ntags, short names that each point at one commit and give people a way in.\n\nMost repositories people work in come with a working tree attached. The files\nyou open in an editor sit in the project directory, and the repository itself\nlives beside them in a hidden `.git` directory. A bare repository has no working\ntree at all. Its directory name conventionally ends in `.git`, it holds only the\nhistory, and it is the form a server keeps, because nobody edits files there;\npeople push to it and fetch from it. Git’s glossary says as much: publishers of\npublic repositories usually make bare ones available. The Git book shows how to\nmake one from an existing project with\n`git clone --bare my_project my_project.git`.\n\nCloning is where Git’s design shows. A clone receives nearly all the data the\nserver has: by default, every version of every file for the whole history of the\nproject comes down with it. Every clone is therefore a complete repository, able\nto stand in for the server if the server is lost. The exceptions are small but\nmatter, and the Git book names them: server-side hooks and similar settings stay\nbehind.\n\nTwo variations come up often. A shallow repository, created by cloning with\n`--depth`, keeps only recent commits; the glossary says the older parents are\n“cauterized away”, and the history can be deepened later with a fetch. A\nsubmodule is a repository held inside another one, with its own history, pinned\nby the outer repository to one exact commit.\n\n## Why it matters\n\nA repository is a project’s memory. When a line of code looks wrong, its history\nsays when it arrived, in which commit, and with what explanation. That is only\nas good as the commits people write, which is why teams that care about their\nhistory put rules on commit messages and enforce them with hooks rather than\ngoodwill.\n\nIt is also the unit that most tooling works on. Access is granted per\nrepository, hooks run per repository, and continuous integration usually starts\nfrom one. Draw the boundary of a repository and you have drawn the boundary of\nwhat one review, one check and one permission covers.\n\nRepositories keep what they are given. A commit that deletes a file adds a new\nstate; it leaves every earlier state where it was, in every clone that already\nholds it. That permanence is the point of version control, and it cuts both\nways: an old version is always recoverable, and so is a password that someone\ncommitted by mistake.\n\nFinally, a repository can hold far more than application code. Infrastructure\ndefinitions, documentation and configuration all gain the same things from it: a\nhistory, a review step and a way to rebuild a known state. A server whose setup\nlives in a repository can be rebuilt by someone who has never seen it.\n\n## What it looks like in practice\n\n[Four repositories built over eighteen months by one person](/portfolio/held-4-repositories-to-one-history-standard/)\nshare one commit standard: a conventional prefix naming the kind of change, a\nscope, a subject under a fixed length, no emojis and no attribution trailers. A\ncommit-message hook in every repository that carries work rejects anything that\nbreaks it, which makes the standard a property of the repository rather than of\nwhoever is committing. The history then shows what the work was. At the\ndocumented July 2026 implementation stage, the largest repository’s history read\n156 feature commits, 133 fixes, 128 documentation, 81 chores, 26 refactors, 20\nstyle, 5 performance and 3 test. The hook stops short of quality: the format is\nchecked and the content is not.\n\nFor the company's own infrastructure, deployed public services and the\nconfiguration of other components, the brief was to have it\n[described in a repository rather than in a head](/portfolio/servers-you-can-rebuild-from-scratch/).\nThe recorded implementation held 12,065 lines of YAML, split into 19 playbooks\nand 34 roles; those counts describe that stage, not the current repository.\nBackup and mail automation are configured there, with operational activation a\nseparate step. The estate can be reproduced from the repository: a host sits in\na tier group whose variables declare the roles it runs, and a converged host\nreports zero changes. Each change takes longer than an edit made directly on the\nserver, and a preflight play was later added in front of the converge.\n\nA repository also keeps what it was given while attention was elsewhere.\n[Work for a different company rode along through a repository restructure](/portfolio/wrote-a-scope-rule-after-a-credential-leak/),\nincluding a scratch log holding live plaintext credentials that sat in the tree\npast every guard for most of the repository’s history. None of it ran, and that\nis exactly why it survived. The answer was a scope rule at the top of the\nrepository’s instructions, one company’s infrastructure and only that, plus a\nquarantine instead of a deletion, so the history stays legible while the secret\nscanner, the vault guard and the emoji check still read the quarantined files.\n\n## Where it goes wrong\n\n- **A secret committed once outlives its deletion.** Removing the file in the\n  next commit leaves it in the previous one and in every clone made since. Treat\n  the credential as public: rotate it first, then decide whether rewriting\n  history is worth the disruption to everyone who has a copy.\n- **A push meets a checked-out branch.** Pushing into a non-bare repository\n  whose current branch is the one being updated would leave its working tree out\n  of step with its history, so Git refuses such a push by default through\n  `receive.denyCurrentBranch`. A repository that people push to should be bare.\n- **A shallow clone answers history questions from part of the history.** A\n  clone made with `--depth` carries only recent commits, so `git log`,\n  `git blame` and any script that derives a version from the last tag see only\n  that slice. Build and release jobs that need the past should fetch the full\n  history.\n- **A local hook stops at the next clone.** Client-side hooks live in\n  `.git/hooks`, and the Git book is explicit that a clone does not copy them. A\n  policy enforced only there ends the day someone clones afresh. Keep the hook\n  scripts tracked in the repository and point `core.hooksPath` at them, or\n  enforce the rule on the server side with `pre-receive`.\n- **Large binaries swell every clone forever.** Because a clone carries every\n  version of every file, each replaced copy of a large binary stays in the\n  history and every new clone downloads all of them.\n- **Files that nothing runs go unread.** A disabled task, a stale inventory or a\n  scratch log still sits in every clone, yet no test, build or deploy touches\n  it, so it escapes review. The repository’s contents should match what the\n  project is responsible for, and anything else should be removed or set apart\n  where the guards can still see it.\n\n## Further reading\n\n- [gitglossary: repository](https://git-scm.com/docs/gitglossary#def_repository)\n  — Git’s own definition, next to bare repository, worktree, shallow repository\n  and submodule.\n- [Getting a Git Repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository)\n  — the two ways to get one, starting fresh in a directory or cloning, and what\n  a clone brings down.\n- [Git Objects](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects) — how\n  the object database stores content under a hash of that content.\n- [gitrepository-layout](https://git-scm.com/docs/gitrepository-layout) — what\n  each file and directory inside a repository is for.\n- [Getting Git on a Server](https://git-scm.com/book/en/v2/Git-on-the-Server-Getting-Git-on-a-Server)\n  — turning an existing repository into a bare one and sharing it.\n- [Git Hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) —\n  client-side and server-side hooks, and why a clone leaves the client-side ones\n  behind.\n\n\u003chttps://engineer.company/glossary/repository/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"How a Git repository is built from objects and refs, why a clone carries the whole past with it, and what a repository keeps long after you wish it did not.","formats":{"gemtext":"https://engineer.company/glossary/repository/index.gmi","gopher":"https://engineer.company/glossary/repository/gophermap","html":"https://engineer.company/glossary/repository/","json":"https://engineer.company/glossary/repository/index.json","markdown":"https://engineer.company/glossary/repository/index.md","pdf":"https://engineer.company/glossary/repository/index.pdf"},"kind":"page","language":"en","title":"What is a repository?","url":"https://engineer.company/glossary/repository/","version":1}