Repository Sync Guide

Branch or tag: choosing what a repository diagram should track

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

Every repository-linked diagram tracks exactly one ref, and the choice between a branch and a tag decides what the diagram means. A diagram on main answers what does the system look like now. A diagram on v3.2.0 answers what did we ship in March. Those are different questions, and a team usually needs both pictures rather than an argument about which one is correct.

Try it free
6 min readFor teams deciding whether their diagram should follow main or freeze at a release

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

150/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

What each choice actually does at sync time

A branch-tracking diagram resolves the head of that branch on every sync. When the head has moved, the sync looks at what moved. When it has not, the sync stops immediately, which is why a quiet week costs nothing.

A tag-tracking diagram resolves the same commit forever, because that is what a tag is. Annotated and signed tags are dereferenced to the commit they wrap rather than to the tag object, each host in its own dialect: on GitHub the tag object is fetched and followed one step, on Azure DevOps the refs listing is called with peelTags=true, on GitLab the tags endpoint already answers with the commit. The tree that gets read is therefore the tree that was tagged. Practically, a tag diagram generates once and then answers unchanged on every later sync, which makes it a record rather than a maintenance obligation.

Ref names with slashes are fine on all three hosts, so release/2026.08 or feature/warehouse-migration work as tracked refs. The picker pulls three pages of a hundred from the provider for each kind, so up to three hundred branches and three hundred tags are offered and the choice is made from what exists rather than typed from memory. Before any request is made the name is checked: a ref containing whitespace, a control character, a :// sequence, a .. traversal, a leading or trailing slash, or an empty path segment is refused outright.

Platform (main)          branch main      resyncs, skips when nothing structural moved
Platform (v3.2.0)        tag v3.2.0       generated once, unchanged thereafter
Platform (warehouse)     branch feature/warehouse-migration   redraws as the branch evolves

One connection, several diagrams

A connection is the repository plus, for a private repo, its token. Diagrams hang off it one per ref, and there is no limit of one. The common arrangement is a living diagram on main plus a frozen one per release tag, which costs one extra generation at release time and nothing afterwards.

The second arrangement worth knowing is the long-lived branch. During a migration, a feature branch is where the new architecture actually exists, and a diagram tracking that branch turns the review into a picture comparison instead of a diff read. When the branch merges, the main diagram catches up on its own and the branch diagram can be unlinked.

On the first sync of any diagram, Datadef reads the repository and then asks what the diagram should show, with a recommendation derived from the file counts it found. The recommendation is arithmetic, not a model call: if the data models, SQL, schemas, and API definitions outnumber the infrastructure, container, and CI files, it proposes the content view, otherwise the architecture one. Answering both creates a sibling diagram on the same ref committed to the other view, which is how a repo ends up with one diagram of the system around the code and one of what the code does.

A Terraform-dominant repository is the exception: it skips the question entirely, because there is one right view of a directory of .tf files and asking about it would be a formality.

Which one to use, by situation

Use main, or whatever your default branch is called, for the diagram everyone links to. This is the one that belongs in the README, in the onboarding doc, and in the wiki page people search for. Its value comes from being current, so daily sync stays on.

Use a release tag when the diagram has to still be true later: a compliance artifact, an architecture record attached to a release, the picture a customer received with a delivery. A tag diagram cannot drift, because the commit under it cannot move.

Use a feature branch for a change big enough to argue about. Once the argument is settled and the branch is merged, delete the diagram or unlink it, the same way you delete the branch.

The related question of how often the main diagram should regenerate is covered in how often should architecture diagrams be updated.

Frozen by intent, not by neglect

A tag diagram is frozen because the ref cannot move. A stale main diagram is frozen because nobody redrew it. Only one of those is a decision. See when to regenerate an architecture diagram.

FAQ

Can one repository connection back more than one diagram?

Yes. A connection is the repository plus its token, and diagrams attach to it one per branch or tag. A typical setup keeps a living diagram on the default branch and one frozen diagram per release tag, all from the same connection.

Does a diagram tracking a tag ever regenerate?

Effectively no. A tag points at a fixed commit, so each sync resolves the same commit as the previous one and stops before generating anything. That makes a tag diagram a permanent record of what that release contained.

Are annotated or signed tags handled correctly?

Yes. An annotated or signed tag points at a tag object rather than directly at a commit, and that object is dereferenced one step to reach the commit it wraps. The tree that gets read is the tree that was tagged.

Can I track a branch whose name contains slashes?

Yes. Names like release/2026.08 or feature/warehouse-migration are valid tracked refs on all three supported hosts, and each path segment is URL-encoded before the request. Branch and tag names are picked from a listing pulled from the provider, up to three hundred of each, rather than typed freehand. Names containing whitespace, control characters, or a .. traversal are rejected before any call is made.

What happens to the branch diagram after the branch is merged and deleted?

The sync can no longer resolve the ref, so it reports a not-found failure and leaves the existing canvas alone. Unlink the diagram at that point: the project keeps its content and simply stops syncing, which is the right end state for a migration picture.