Introduction

Renaming a Git remote changes the local shorthand name you use to reference a remote repository URL. The command is git remote rename <old> <new>. This updates all remote-tracking branches (e.g., origin/main becomes upstream/main), configuration entries, and refspecs. Renaming does not affect the remote server — it is purely a local operation. Common reasons include switching from origin to a more descriptive name when working with multiple remotes (e.g., upstream, fork, deploy).

Viewing Current Remotes

1# List remote names
2git remote
3# origin
4
5# List remote names with URLs
6git remote -v
7# origin  https://github.com/user/repo.git (fetch)
8# origin  https://github.com/user/repo.git (push)

Renaming a Remote

1# Syntax
2git remote rename <old-name> <new-name>
3
4# Rename "origin" to "upstream"
5git remote rename origin upstream
6
7# Verify the change
8git remote -v
9# upstream  https://github.com/original-author/repo.git (fetch)
10# upstream  https://github.com/original-author/repo.git (push)

All remote-tracking branches update automatically:

1# Before rename
2git branch -r
3# origin/main
4# origin/develop
5# origin/feature-x
6
7# After renaming origin to upstream
8git branch -r
9# upstream/main
10# upstream/develop
11# upstream/feature-x

Common Workflow: Fork with Upstream

When you fork a repository, you typically want origin pointing to your fork and upstream pointing to the original repository.

1# Clone your fork
2git clone https://github.com/your-user/repo.git
3cd repo
4
5# "origin" points to your fork by default
6git remote -v
7# origin  https://github.com/your-user/repo.git (fetch/push)
8
9# Add the original repo as "upstream"
10git remote add upstream https://github.com/original-author/repo.git
11
12git remote -v
13# origin    https://github.com/your-user/repo.git (fetch/push)
14# upstream  https://github.com/original-author/repo.git (fetch/push)
15
16# Fetch upstream changes
17git fetch upstream
18git merge upstream/main

Removing and Re-Adding (Alternative)

If renaming causes issues with complex refspecs, you can remove and re-add the remote.

1# Save the URL first
2git remote get-url origin
3# https://github.com/user/repo.git
4
5# Remove the old remote
6git remote remove origin
7
8# Add with the new name
9git remote add upstream https://github.com/user/repo.git
10
11# Fetch to recreate remote-tracking branches
12git fetch upstream

Changing the Remote URL (Not Rename)

If you want to change where a remote points (not its name), use set-url:

1# Change the URL for "origin"
2git remote set-url origin https://github.com/new-user/repo.git
3
4# Set separate fetch and push URLs
5git remote set-url origin https://github.com/user/repo.git          # fetch
6git remote set-url --push origin [email protected]:user/repo.git       # push via SSH
7
8git remote -v
9# origin  https://github.com/user/repo.git (fetch)
10# origin  [email protected]:user/repo.git (push)

Updating Local Branch Tracking

After renaming a remote, local branches that track old remote names need updating.

1# Check which remote a branch tracks
2git branch -vv
3# * main   abc1234 [upstream/main] Latest commit message
4
5# If tracking is broken, set it manually
6git branch --set-upstream-to=upstream/main main
7git branch --set-upstream-to=upstream/develop develop

Common Pitfalls

• Remote name already exists: git remote rename origin upstream fails if upstream already exists. Remove or rename the existing remote first: git remote remove upstream or choose a different name.
• Hardcoded remote names in scripts: CI/CD pipelines, deployment scripts, and Makefiles often reference origin by name. After renaming, search your project for hardcoded remote names and update them. Check .github/workflows/, Makefile, deploy.sh, and similar files.
• Forgetting to update branch tracking: After renaming, existing local branches may still reference the old remote name in their tracking configuration. Use git branch --set-upstream-to=<new-remote>/<branch> to update each tracked branch.
• Confusing rename with URL change: git remote rename changes the local name, not the URL. To change where a remote points, use git remote set-url <name> <new-url>. These are separate operations.
• Losing remote-tracking branches on remove/re-add: Using git remote remove followed by git remote add deletes all remote-tracking branches for that remote. You must git fetch after re-adding to recreate them. The git remote rename command preserves tracking branches, so prefer it over remove/add.

Summary

• Use git remote rename <old> <new> to rename a remote — this updates all tracking branches automatically
• Use git remote -v to verify remote names and URLs
• Use git remote set-url to change the URL without renaming
• Update local branch tracking with git branch --set-upstream-to if needed after renaming
• Prefer rename over remove/add to preserve remote-tracking branches