Create, rename, move, delete

Why this matters

Documentation work is mostly moving things around: a new page, a renamed guide, an old file removed, a folder restructured. Git handles all of it, but it watches content, not your editor's actions, so a rename looks like a deletion plus a new file until you stage both. Knowing this makes reorganizations calm instead of alarming.

What Git notices

Git compares the working tree with the last commit. It notices:

• New file: exists on disk, not in the last commit → untracked until you git add it.
• Changed file: content differs → modified.
• Missing file: in the last commit, not on disk → deleted (not staged).
• Rename or move: a file disappeared and a new one with the same (or nearly the same) content appeared → shown as a rename once both sides are staged.

Git does not notice empty folders at all: it tracks files, and a folder exists in history only because a file is inside it.

Renaming and moving

Rename in your editor or file manager, and look:

$ git status

On branch main
Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	deleted:    docs/notes.md

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	docs/scratch.md

Stage the folder (or both files) and Git recognizes the rename:

$ git add docs/
$ git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	renamed:    docs/notes.md -> docs/scratch.md

git mv does the rename and the staging in one step:

$ git mv docs/faq.md docs/questions.md
$ git status -s

R  docs/faq.md -> docs/questions.md

Both routes give the same result. Moving to another folder is the same as renaming: git mv docs/faq.md docs/help/faq.md (the target folder must exist).

Deleting

Delete in the editor and Git reports deleted:; stage the deletion with git add <file> (yes, add stages deletions too) or use git rm, which removes the file from disk and stages the removal:

$ git rm docs/scratch.md

rm 'docs/scratch.md'

$ git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	deleted:    docs/scratch.md

If the file is already gone from disk, git rm <file> still works and stages the deletion. To stop tracking a file without deleting it (typically something that should have been ignored): git rm --cached <file>.

The deleted file is not lost: it is in every earlier commit, and lesson 12.5 brings it back.

Empty folders

$ mkdir docs/drafts
$ git status -s

Nothing. Git will not commit an empty folder. The convention is to put a placeholder file inside, usually named .gitkeep (any name works; .gitkeep signals intent):

$ touch docs/drafts/.gitkeep
$ git add docs/drafts/.gitkeep

Conversely, deleting the last file in a folder makes Git forget the folder; a colleague pulling the change sees the folder disappear.

In the tools

Common mistakes

• Renaming a file and only staging the new name. The commit adds a file and leaves the old one "deleted, not staged". Stage both paths, or use git mv.
• Committing a rename together with a rewrite. Two commits.
• Creating an empty folder and expecting colleagues to see it. Add a .gitkeep.
• git rm on a file with uncommitted edits. Git refuses (has local modifications); decide whether to commit or discard those edits first.
• Renaming only the letter case (Readme.md → README.md) on macOS or Windows, where the file system ignores case. Use git mv Readme.md README.md; Git handles it even where the OS pretends nothing changed.