Why Use a Bare Git Repository? Mastering git clone --mirror for Backups and Migration

Understanding Bare Git Repositories

In standard Git workflows you work with a repository that has a working directory and a .git directory. A bare repository contains only the .git data and no working files, making it unsuitable for direct development but ideal for central storage and mirroring.

What Is a Bare Repository?

A bare repository consists solely of the internal Git files such as HEAD, objects, refs, and configuration files. It lacks a working directory, so you cannot edit source files directly inside it.

Why git clone --mirror Produces a Bare Repository

The git clone --mirror command creates an exact local copy of a remote repository, replicating every commit object, all references ( refs/heads/*, refs/remotes/*, refs/tags/*), and even notes. By using a bare format, Git avoids interference from a working directory and guarantees that the local mirror matches the remote repository byte‑for‑byte.

Typical Directory Layout of a Bare Repository

HEAD

: points to the default branch reference (e.g., ref: refs/heads/main). branches: rarely used in newer Git versions; branch data lives in refs/heads. config: repository configuration, including remote URLs. description: human‑readable description for tools like GitWeb. hooks: scripts that run on specific Git events (e.g., pre-receive). info: auxiliary information such as an exclude file. objects: stores all Git objects—commits, trees, blobs, and tags. packed-refs: compressed reference file for fast lookup. refs: contains pointers for branches, tags, and remote‑tracking branches.

Common Use Cases and How to Work With a Bare Repository

Central shared repository : Create a bare repo on a server with git init --bare myproject.git. Team members clone it, work locally, and push changes back to the central bare repo.

Backup and migration : Use git clone --mirror to create a full local mirror of a remote repository. Update the backup later with git remote update. To migrate, push the mirror to a new remote using git push --mirror <new_remote_url>.

Step‑by‑Step Example: Backing Up and Migrating a GitLab Project

Create the mirror :

git clone --mirror https://old-gitlab.com/mygroup/myproject.git myproject_backup.git

This creates a bare repository named myproject_backup.git containing the complete history.

Update the backup (optional) :

cd myproject_backup.git
git remote update  # fetches new commits and updates references

Migrate to a new GitLab instance :

cd myproject_backup.git
git push --mirror https://new-gitlab.com/mygroup/myproject.git

The --mirror flag forces all branches, tags, and refs to be pushed, creating an exact replica at the new location.

Conclusion

A bare Git repository is a special form that stores only the .git metadata without a working directory. It is essential for centralized code hosting, reliable backups, and precise repository migrations, especially when automated scripts need a clean, immutable copy of a remote repository.