What is git clone --mirror?

The git clone --mirror command creates a bare repository that is a complete, exact replica of the source repository, ideal for maintaining an up-to-date mirror. It results in a bare repo with no editable working files, serving primarily as a remote repository for other developers or systems to clone from, rather than for direct development.

Understanding Bare Repositories

When you typically clone a Git repository, you get a "normal" repository with a .git directory (which holds all the repository's history, objects, and references) and a working directory containing the actual files checked out at a specific commit.

A bare repository, on the other hand, consists only of the contents of the .git directory. It does not have a working directory, meaning there are no visible project files to edit or modify directly. This design makes bare repositories unsuitable for development but perfect for serving as central repositories on a server, backups, or as a source for other clones.

Key Characteristics of git clone --mirror

The --mirror option for git clone goes beyond a simple bare clone by ensuring a truly identical replica. Here's what it entails:

• Complete Reference Cloning: git clone --mirror will clone all the extended refs of the remote repository. This includes not only all branches and tags but also all remote-tracking branches (refs/remotes/), and even other less common references (like refs/pull/ for some platforms). This ensures the mirror is an exact, byte-for-byte copy of the source's internal structure.
• Maintains Tracking Configuration: It meticulously maintains the remote branch tracking configuration. This means the mirror repository knows exactly how to map local references to the original remote's references, making future updates seamless.
• Overwrites All Refs on Update: When you run git remote update on a repository created with --mirror, it will aggressively fetch and overwrite all refs from the origin repo, ensuring that your mirror is always a precise, up-to-date copy of the source. Any local changes or discrepancies in the mirror's refs would be overwritten to match the upstream.

Why Use git clone --mirror?

This command is invaluable for several scenarios where an exact, syncable replica of a repository is required:

• Repository Backup: Creating a full, recoverable backup of an existing repository, including all its branches, tags, and remote tracking information.
• Migrating Repositories: Moving a repository from one hosting service to another (e.g., from GitLab to GitHub, or an internal server to a cloud service) while preserving all historical data and references.
• Setting Up an Internal Git Server: Providing a central, authoritative source for your team's repositories on a self-hosted Git server.
• Local Caching for CI/CD: Speeding up Continuous Integration/Continuous Deployment pipelines by having a local, frequently updated mirror that build servers can clone from quickly.
• Maintaining Public Mirrors: Offering alternative access points for open-source projects.

How to Use git clone --mirror

1. Cloning a Repository as a Mirror

To create a mirror, simply use the git clone --mirror command followed by the URL of the source repository and the desired name for your local mirror directory:

git clone --mirror <repository-url> <mirror-name>.git

Example:

git clone --mirror https://github.com/git/git.git git-mirror.git

This will create a bare repository named git-mirror.git in your current directory.

2. Updating the Mirror

To synchronize your mirror with the upstream source repository, navigate into the mirror directory and run git remote update:

cd git-mirror.git
git remote update

This command will fetch all new changes and overwrite all refs from the origin repo, ensuring your mirror is an exact replica of the current state of the source repository.

git clone --mirror vs. git clone --bare

While both --mirror and --bare create bare repositories, there's a crucial distinction in their behavior and intent:

Feature	git clone --bare	git clone --mirror
Purpose	Creates a bare repository for server-side hosting or a simple copy.	Creates a bare repository specifically for mirroring, designed for exact replication and easy updates.
Refs Cloned	Clones all local branches and tags, but typically only a subset of remote-tracking branches.	Clones all extended references (refs/*), including all remote-tracking branches (refs/remotes/*).
Remote Tracking	Does not maintain special remote tracking configuration for subsequent updates.	Maintains specific remote branch tracking configurations, ensuring the mirror precisely tracks the original.
Update Behavior	git remote update might not aggressively overwrite all local refs to match the upstream.	git remote update is configured to overwrite all refs from the origin repo, ensuring an exact copy.
remote.origin.url	Points to the original repository.	remote.origin.url points to the original repository; remote.origin.mirror is set to true.
Working Directory	No working directory (bare).	No working directory (bare).
Editable Files	No editable working files.	No editable working files.

In essence, --mirror is a more comprehensive and robust option when your goal is to maintain a perfect, up-to-date replica of a remote repository.

Conclusion

git clone --mirror is a powerful and essential command for anyone needing to maintain an exact, syncable copy of a Git repository. By creating a bare repository that clones all extended references and automatically overwrites its refs to match the origin upon update, it simplifies tasks like backups, migrations, and setting up robust mirroring infrastructure. Understanding its nuances, especially compared to --bare, allows developers and system administrators to leverage Git more effectively for repository management.