Moving Your Repo
Sooner or later, every project gets moved — renamed, reorganised into a new folder structure, or copied to a different computer entirely. Git handles this far better than most tools, but only if you understand what's actually stored where. This chapter walks through the common ways a move goes wrong, and the correct way to do each one.
While reorganising a website project folder (renaming it and moving content into a new structure), a nested git repository inside one of the subfolders lost its .git directory during the move — but the parent repository still had a recorded reference to it as a submodule-like "gitlink," pointing at a commit that no longer existed anywhere. Running git status afterward showed the entire subfolder collapsed into a single confusing M website line instead of the actual file changes inside it — because git could no longer see into a folder it expected to be its own repository.
The fix was straightforward once diagnosed: the broken reference simply needed removing from the parent repo's tracking (or the nested .git needed restoring, if a backup existed). The real lesson is the diagnosis step — recognising why a folder was behaving strangely, rather than assuming something was randomly broken.
What Actually Lives Where
Understanding a move starts with knowing exactly what makes a folder a git repository in the first place — covered back in Chapter 2, but worth restating here because it's the entire key to this chapter: the hidden .git folder is the repository. Everything else — your actual files — is just the working directory, recreatable from history at any time.
Scenario: Moving a Folder on the Same Machine
This is the safest move of all, and usually completely uneventful — as long as you move the entire folder, including the hidden .git directory, together, as one unit.
$ mv old-project-folder/ new-location/project/
$ cd new-location/project
$ git status
On branch master
nothing to commit, working tree clean
.git) behind, depending on the OS and settings — exactly what likely happened in the incident above.Verifying a move went cleanly
git rev-parse --show-toplevel from inside the moved folder — if it returns the new path correctly, the repository moved with it.git status and a full, intact git log confirm history survived the move completely.Scenario: Moving to a Different Machine
Moving between machines is where people most often reach for risky manual copying. There's almost always a cleaner option already covered in this course:
git clone (Chapter 5) — full history, correctly configured remote, zero risk of partial copies..git folder or large numbers of small files inside it..git/objects/. Sync conflicts, partial uploads, or sync pauses mid-write can corrupt a repository in ways that are hard to diagnose later. If a project lives inside a synced folder, treat GitHub (or another remote) as the real source of truth, and don't rely on the sync tool itself as your backup strategy.
Scenario: Renaming a Repository
Renaming the local folder is identical to moving it — .git doesn't care what the containing folder is named. Renaming the GitHub repository itself is different and needs one extra step:
$ git remote set-url origin https://github.com/yourname/new-repo-name.git
$ git remote -v
origin https://github.com/yourname/new-repo-name.git (fetch)
origin https://github.com/yourname/new-repo-name.git (push)
GitHub actually redirects the old URL automatically for a good while after a rename — but updating it explicitly avoids relying on that redirect indefinitely, and avoids confusion for anyone else with the repo cloned.
Diagnosing a Broken Move
If something looks wrong after a move, work through this in order rather than guessing:
$ git rev-parse --show-toplevel
$ # Is the remote URL still correct?
$ git remote -v
$ # Is history intact?
$ git log --oneline -5
$ # Is a subfolder behaving like a broken gitlink rather than showing real changes?
$ git ls-files -s <suspicious-folder>
160000 90bafe80c9... 0 suspicious-folder
# Mode 160000 = git is tracking this as a submodule/gitlink, not an ordinary folder
That last command is exactly what diagnosed the real incident described at the top of this chapter — mode 160000 in git ls-files output is the unambiguous sign that git considers a folder its own separate repository, whether or not that's actually still true on disk.
Chapter 9 Quick Reference
- The .git folder IS the repository — everything else is recreatable from it
- Moving on the same machine: move the whole folder including .git as one unit; verify before deleting the old copy
- Moving to a new machine: prefer git clone over manual copying whenever the project is already on GitHub
- Cloud-synced folders (OneDrive/Dropbox) can mishandle .git's many small files — treat a real remote as your source of truth, not the sync tool
- Renaming on GitHub: update with git remote set-url origin <new-url> afterward
- Diagnosing a broken move: git rev-parse --show-toplevel → git remote -v → git log → git ls-files -s on any suspicious folder
- Mode 160000 in git ls-files output = git is treating that folder as a separate repository (gitlink) — the exact signature of the broken-move incident in this chapter
- Next chapter (Scenario): two people on the same branch — push rejections, simple conflicts, and staying in sync