There is no Git command to rename a repository, because Git has no concept of one. The name lives on the host and in your directory name, and everything else is a URL that needs updating.
This trips people up because git mv exists and sounds like it should be the answer. It renames files inside a repository. The repository itself has no name from Git’s point of view — it is a directory containing a .git folder, and what you call that directory is between you and your filesystem.
So renaming is a host-side action followed by a cleanup list. The list is short, and skipping items on it is how a rename ends up causing a broken deploy a week later.
Table of contents
- Rename on the host first
- Update the local clone
- The list of things that point at the old name
- Submodules and Go modules: the two that bite
- Renaming versus forking versus starting fresh
- Reconnecting deployments
- How this fits the rest of the stack
- FAQ
Rename on the host first
On GitHub: repository Settings, the Repository Name field, type the new name, click Rename. GitLab and Bitbucket have equivalent settings, though GitLab distinguishes the display name from the path — changing the path is what changes the URL.
The host sets up a redirect from the old URL to the new one. That redirect is genuinely useful and genuinely not something to rely on:
git fetchandgit pushagainst the old URL keep working, usually with a warning.- The redirect breaks the moment someone creates a new repository with the old name — which, in an active organisation, is a real possibility.
- Not every integration follows redirects. Some CI systems and deployment tools fail rather than following.
Treat the redirect as a grace period for updating things, not as a permanent arrangement.
Update the local clone
Two separate things, and only one is necessary.
The remote URL, which matters:
git remote set-url origin [email protected]:acme/new-name.git
git remote -v # verify
git fetch origin # confirm it worksThe local directory name, which is cosmetic:
cd ..
mv old-name new-name
cd new-nameGit does not care what the directory is called — nothing inside .git records it. Rename it to match anyway, because a directory called old-name whose remote points at new-name is exactly the kind of small inconsistency that costs someone twenty minutes in six months.
Every developer with a clone needs the set-url. Post the one-line command in the team channel rather than describing where the setting lives, and remember that anyone who does not run it will keep working silently via the redirect until it stops existing.
The list of things that point at the old name
This is where renames actually go wrong. Work through it:
- CI/CD configuration — pipeline files, deployment integrations, anything with the repository path in it.
- Webhooks in and out. Outbound webhook URLs from the host update themselves; anything registered elsewhere pointing back at the repository does not.
- Submodule references. Any repository including this one as a submodule has the old URL in its
.gitmodules. - Package registries. A published package’s repository URL, and any Go module path — which is a special case, see below.
- Documentation and READMEs, including badge image URLs, which quietly 404.
- Deploy keys and secrets scoped to the repository, which usually survive but are worth confirming.
- Bookmarks, issue templates, and anywhere the URL was pasted into a wiki.
Grep your organisation for the old name before you announce the rename is done. It is faster than discovering the list one broken thing at a time.
Submodules and Go modules: the two that bite
Submodules. A repository that includes the renamed one as a submodule has the old URL committed in .gitmodules. Edit the file, then:
git submodule sync --recursive
git add .gitmodules && git commit -m "Update submodule URL after rename"git submodule sync is the step people miss — editing .gitmodules alone does not update the working copy’s .git/config, so the submodule keeps fetching from the old place.
Go modules. In Go, the module path is the repository URL. Renaming a repository renames the module, and every consumer’s import statements break. There is no redirect that fixes this.
// go.mod
module github.com/acme/new-nameThat is a breaking change for anyone importing your package, and the module proxy caches the old path indefinitely. If the module is public, treat renaming as a major-version-style event: announce it, and consider whether the rename is worth it at all.
Renaming versus forking versus starting fresh
Worth a moment before doing it. Renaming preserves everything: history, issues, pull requests, stars, watchers, releases. That is usually what you want and the reason to rename rather than create a new repository and push into it.
The cases where a rename is the wrong tool:
- Splitting a repository. That is
git filter-repoor a subtree extraction, not a rename. - Removing sensitive history. A rename changes nothing about what is in the history.
- Changing the owner. That is a transfer, a separate operation with its own permission consequences.
- Public Go modules with real consumers. The import-path breakage often outweighs the tidier name.
If the only motivation is that the name is slightly wrong, weigh it against the cleanup list above. Sometimes the honest answer is that the name is fine.
Reconnecting deployments
The failure worth planning for: a deployment integration keeps building from the old repository reference and nobody notices, because builds keep succeeding — they are just building code nobody is pushing to any more.
After a rename, trigger a deploy and check the build log names the repository you expect. That is a ten-second check that catches an entire class of confusing incident.
On RunxBuild, services and static sites build from a connected GitHub repository, so a rename means reconnecting the project. The deploy log shows which repository and which commit produced each build, which is exactly where you confirm the reconnection took.
How this fits the rest of the stack
Renaming is a host-side action plus a cleanup list: git remote set-url in every clone, submodule URLs synced, CI and deployment integrations repointed, and the redirect treated as a grace period rather than a fix. Then trigger a build and read the log to confirm it is coming from the right place. The RunxBuild hosting calculator is where the services building from that repository turn into a monthly number.
Useful related references:
- Self-Hosting Git: From Bare Repo to Gitea to GitLab, Without the Headache
- Linux: How to Check If a User Account Name Was Changed
- Install Docker on Debian 12 (Bookworm): apt repo and post-install
- Services on RunxBuild
FAQ
Is there a Git command to rename a repository?
No. Git has no concept of a repository name — it is a directory containing a .git folder. Rename it on the host through the web interface, then update each clone with git remote set-url. git mv renames files inside a repository, not the repository.
Do I need to re-clone after a repository is renamed?
No. Run git remote set-url origin <new-url> in the existing clone and optionally rename the local directory to match. Nothing inside .git records the repository name, so the clone is otherwise unaffected.
Does the old repository URL keep working?
Most hosts redirect it, and fetches and pushes generally keep working. But the redirect breaks if someone creates a new repository with the old name, and some CI and deployment tools do not follow redirects. Update the URLs rather than relying on it.
What breaks when I rename a Go module’s repository?
Every import path. In Go the module path is the repository URL, so consumers must update their imports and the module proxy caches the old path. For a public module with real users, treat this as a breaking change and weigh it carefully.
How do I update a submodule after the repository it points to is renamed?
Edit the URL in .gitmodules, run git submodule sync --recursive to push the change into the working copy’s config, then commit .gitmodules. Skipping the sync step leaves the submodule fetching from the old location.