Git log --follow: Trace a File History Across Renames

You inspect a documentation file's history and see only a recent rename commit, even though the content clearly existed earlier. Before assuming the history is lost, try Git log --follow. It helps reconnect an investigation when a file's path has changed.

1. Start with one specific file

Run the commands from the repository root and replace the example path with your actual file. Here, a document previously named setup.txt has become onboarding.txt:

git --no-pager log --oneline HEAD -- onboarding.txt
git --no-pager log --follow --oneline HEAD -- onboarding.txt

The Git log documentation describes --follow as continuing history across renames, with support for a single file at a time. Do not supply a directory or a list of files and expect complete rename histories for all of them.

2. Read the rename evidence

git --no-pager log --follow --name-status HEAD -- onboarding.txt

For a simple rename with no content edits, you may see a line like this:

R100    setup.txt    onboarding.txt

The two paths identify the old and new names. In the article's test with one commit creating setup.txt and another renaming it, --follow returned both commits; a normal query for the new path returned only the rename commit.

Do not draw business conclusions from a status line alone. Next, locate the commit that changed the content, read its message, and compare the change with related requirements or tests.

3. Inspect content changes in the same history

git --no-pager log --follow -p --no-ext-diff --no-textconv HEAD -- onboarding.txt

This adds patches showing content changes. The two final options disable external diff helpers and text conversion for this inspection. For a long file, start with the concise commit list and read the detailed changes after identifying the period that matters.

If you inspect an older commit separately in another tool, remember to use the filename that existed at that point. Looking for onboarding.txt in a commit containing only setup.txt can hide relevant evidence even when you have selected the right commit.

4. Keep the limitations in mind

Git detects renames by comparing content, rather than relying on a permanent identity record for every file. Renaming and substantially rewriting a file together can be harder to trace. Splitting a file into several files, or combining several into one, also calls for manual inspection of the related paths.

A short result is not necessarily the entire relevant history. Check the starting point HEAD, the branch you are inspecting, and whether your clone has limited history. With branches and merges, cross-check related commits instead of treating one query as exhaustive evidence.

5. Record a reproducible conclusion

A useful investigation note records the current name, previous name, rename commit ID, and any important content-change commit. Separate observations from assumptions about intent; if no issue or documentation confirms the reason, say so.

The compact workflow is to select one file, list its history with --follow, inspect the earlier name, and read the relevant patches. None of these steps requires checking out an old version or changing your working tree.