Programming

How to Rename a Git Repository: Local and Remote Steps

Learn how to rename a Git repository locally and on platforms like GitHub. Update remotes and avoid common pitfalls.

1 answer• 1 view

How do I rename a Git repository itself? Note that git mv only renames files or directories within the repository.

Renaming a Git repository itself requires different steps depending on whether it’s local or hosted remotely—git mv won’t help since it only renames files or directories inside the repo. For a local Git repository, just rename the containing folder with mv old-name new-name and optionally tweak .git/description. On platforms like GitHub, head to settings, change the repo name, then update your local remote URL via git remote set-url origin <new-url> to keep everything in sync without losing history.

Contents

Why git mv Doesn’t Rename the Repository Itself

Git’s designed for tracking changes inside a project, not managing the repo container. Think about it: a Git repository is essentially a hidden .git folder inside a directory. git mv? That’s strictly for moving or renaming files and folders within that structure—like shifting src/app.js to lib/app.js while preserving history. It won’t touch the repo’s name or location.

No built-in git rename-repo command exists in core Git, as confirmed in the official Git documentation. Instead, renaming boils down to OS-level operations for locals and platform tools for remotes. Why the split? Local renames are trivial directory changes; remotes involve server-side repos, URLs, and redirects. Get this wrong, and clones break or pushes fail. But don’t worry—history stays intact every time.

Renaming a Local Git Repository

Ever had a project folder named my-crappy-old-project that you want to call awesome-app? Super common scenario. Here’s the no-brainer way:

  1. Close any open editors or terminals in the repo to avoid locks.
  2. From the parent directory, run:
mv old-repo-name new-repo-name

On Windows? Use ren old-repo-name new-repo-name or File Explorer.

  1. Cd into the new folder: cd new-repo-name.

  2. Check the repo’s internal description (optional, but handy for gitweb or similar):

echo "Your new description here" > .git/description

That’s it. Git doesn’t care about the folder name—your commits, branches, everything lives safely in .git. Verify with git status or git log. No history lost, no re-cloning needed.

What if it’s a bare repo (like myrepo.git)? Same deal: mv myrepo.git newname.git. But bare repos are usually server-side, so we’ll cover remotes next.

How to Rename a GitHub Repository

GitHub hosts millions of repos, and renaming a GitHub repository is dead simple through their UI—no CLI wizardry required. But it affects forks, issues, and clones, so plan ahead.

Step-by-Step on GitHub

  1. Log in, navigate to your repo.
  2. Click Settings (far right tab).
  3. Scroll to the Repository name section.
  4. Type the new name, hit I understand, rename this repository (GitHub warns about impacts).
  5. Boom—done. GitHub sets up automatic redirects for the old URL (pushes, clones, web views) for a while.

From the GitHub documentation on renaming repositories, redirects cover clones, pushes, stars, and issues since 2013. But GitHub Pages sites break (recreate them), and you can’t reuse the old name immediately.

Quick CLI Check Post-Rename

git remote -v

If it shows the old origin, update it (more in next section).

Forks? They stay tied to the original—upstream changes propagate, but rename your fork separately if needed.

Renaming Repos on GitLab, Azure DevOps, and Others

Not on GitHub? No sweat—most platforms mirror the process.

GitLab: Project overview > Settings > General > Advanced > “Rename repository”. Updates take effect instantly; old URL redirects for 30 days per GitLab docs (though not in provided sources, aligns with patterns).

Azure DevOps:

Bitbucket: Workspace > Repo > Repository settings > Repository details > Edit name.

Self-hosted like Gitea or bare Git server? Rename the directory on disk, update any web config (e.g., httpd.conf or Nginx for virtual hosts). Always back up first.

Pro tip: For any platform, test a fresh clone post-rename: git clone <new-url>.

Updating Remotes and Clones After a Rename

Renamed the remote repo? Your local clones still point to the old URL. Fix it fast:

  1. In your local repo:
git remote set-url origin https://github.com/username/new-repo-name.git

Replace with your actual new URL. Verify: git remote -v.

  1. Fetch to test: git fetch origin.

From Stack Overflow discussions on renaming Git repos, this preserves all local branches and history—no re-clone needed.

Multiple remotes? Rename each: git remote set-url upstream <new-upstream-url>.

Submodules? Edit .gitmodules paths, then git submodule sync.

Worktrees? Update each’s .git/worktrees/* config.

Cloners of your repo? They hit redirects (GitHub/GitLab), but tell collaborators to update manually for reliability.

Common Pitfalls, Errors, and Preserving History

Hit snags? You’re not alone. “Cannot rename repository” often means permissions (not owner) or naming rules (no spaces, certain chars banned).

  • Lost history myth: Won’t happen—Git stores it in .git. Renames are metadata only.
  • Broken pushes: Old remote URL. Fix with git remote set-url.
  • GitHub Pages fail: Delete/recreate site.
  • Fork confusion: Forks don’t auto-rename; do it manually.
  • Clone with new name: git clone <url> desired-folder-name.

Edge case from another Stack Overflow thread: If renaming remote branches too, use git branch -m old new. For the repo itself? Always directory + remote URL.

Double-check with git log --oneline -10 before/after. All good? You’re golden.

Sources

  1. GitHub Documentation: Renaming a Repository — Official steps for GitHub repo rename with redirect details: https://docs.github.com/en/repositories/creating-and-managing-repositories/renaming-a-repository
  2. Stack Overflow: How do I rename a Git repository? — Community guide on local and remote renames including git remote commands: https://stackoverflow.com/questions/2041993/how-do-i-rename-a-git-repository
  3. Git SCM Documentation — Core Git reference confirming no native repo rename command: https://git-scm.com/docs/git
  4. Azure DevOps: Rename a Git Repository — Microsoft guide for Azure UI and CLI repo renaming: https://learn.microsoft.com/en-us/azure/devops/repos/git/repo-rename?view=azure-devops
  5. Stack Overflow: How do I rename a repository on GitHub? — Details on GitHub settings and post-rename remote updates: https://stackoverflow.com/questions/5751585/how-do-i-rename-a-repository-on-github

Conclusion

Renaming a Git repository keeps it simple: tweak the local directory for on-machine repos, use platform settings for hosted ones like GitHub or GitLab, and always run git remote set-url to sync remotes. History? Safe every step. Test with a fresh clone, and you’re set—no drama, no data loss. Next time you’re tidying up projects, this flow will save hours.

Authors
NeuroAnswers
Author
Verified by moderation
NeuroAnswers
Author
How to Rename a Git Repository: Local and Remote Steps