Introduction

Git does not have a built-in "archive branch" state. A branch is just a movable reference, so archiving is really a convention: preserve the commit history in a way that is still recoverable, while removing the branch from normal day-to-day work.

The right approach depends on why you are archiving. Sometimes a tag is enough. Sometimes you want to keep the branch but move it under a naming prefix such as archive/. Sometimes you want to delete the branch after merging because the commits are already safely reachable from the main history.

Option 1: Tag and Delete the Branch

If the branch is finished and you mainly want a permanent bookmark, create a tag at the branch tip and then delete the branch.

1git checkout main
2git tag archive/feature-login feature/login
3git branch -d feature/login
4git push origin archive/feature-login
5git push origin --delete feature/login

This works well when the branch has already been merged and you only need a stable reference to the final commit.

Option 2: Rename the Branch Under an Archive Prefix

If you want to keep the branch as a branch, rename it rather than deleting it.

1git branch -m feature/login archive/feature-login
2git push origin archive/feature-login
3git push origin --delete feature/login
4git push --set-upstream origin archive/feature-login

This preserves branch behavior while moving it out of the active naming space. Many teams use prefixes such as archive/, attic/, or legacy/.

Option 3: Delete Merged Branches and Rely on Main History

For short-lived feature branches, the cleanest archive is often no branch at all. Once the branch is merged, the commits still exist in the repository history.

git branch --merged main
git branch -d feature/login
git push origin --delete feature/login

If the merge commit or squashed commit is on main, the work is already preserved. Keeping the branch name forever may just create clutter.

How to Inspect Before Archiving

Before deleting or renaming anything, confirm whether the work is merged and whether anyone still depends on the remote branch.

git branch --all
git log --oneline --graph --decorate --all
git merge-base --is-ancestor feature/login main && echo merged

That last command is especially useful in scripts and release checklists because it tells you whether the branch tip is already reachable from main.

When Tags Are Better Than Branches

Tags are ideal when you want an immutable marker. A tag says "this commit matters" without implying ongoing development.

Branches are better when you want to keep the option of continued work, cherry-picks, or branch-based tooling.

As a rule:

• Use a tag for completed historical snapshots.
• Use an archive/ branch for dormant but potentially reusable work.
• Delete the branch entirely when the main branch already preserves the useful history.

Remote Hosting Considerations

GitHub, GitLab, and Bitbucket may have extra branch settings, protections, or pull-request links. Renaming or deleting a remote branch can affect open pull requests, CI jobs, and deployment rules.

Check for:

• Open pull requests targeting or sourced from the branch
• Protected branch rules
• Automation that matches branch names
• Teammates with local branches tracking the old remote name

Archiving is often more about team workflow than about Git mechanics.

Common Pitfalls

The biggest mistake is deleting an unmerged branch without creating another reference first. If the commits are not reachable from a tag, another branch, or the main history, recovery becomes harder.

Another common problem is assuming local deletion also removes the remote branch. It does not. You need an explicit remote delete push.

Be careful when renaming branches that active pull requests or CI pipelines still use. A neat archive can accidentally break automation if naming patterns are hard-coded.

Finally, avoid the word "archive" if your team already uses it for frozen release branches with different semantics. Naming conventions should be clear and stable.

Summary

• Git has no native archive state for branches.
• The usual archive patterns are tagging, renaming under archive/, or deleting merged branches.
• Use tags for immutable historical markers.
• Use archive-prefixed branches when you want to preserve a dormant line of development.
• Verify merge status and remote dependencies before removing or renaming branches.