Navigating the complex waters of version control with Git can sometimes feel like a detective mission, especially when files mysteriously disappear from their original locations, only to reappear under a new name. This common scenario often leaves developers scratching their heads, wondering how to REALLY show logs of renamed files with Git effectively. While Git is incredibly powerful, its default logging commands don’t always highlight file renames as clearly as one might hope. This can obscure crucial historical context, making it difficult to understand a file’s journey through your project. Fortunately, Git provides robust mechanisms specifically designed to track these transformations, ensuring that no file’s history is lost, regardless of its name changes. Understanding these specialized commands is key to unlocking a comprehensive view of your repository’s evolution and maintaining full traceability of your codebase.

Understanding Git’s Rename Detection Mechanism

Git doesn’t explicitly store “rename” operations; instead, it detects them by comparing file content between commits. When you move or rename a file, Git sees it as a deletion of the old file and an addition of a new one. However, during various operations like git diff or git log, Git employs a clever heuristic to identify if the content of a “deleted” file is significantly similar to an “added” file. This process is known as Git rename detection, and it’s remarkably sophisticated, allowing Git to infer renames even when the file content has undergone minor modifications.

The core of this detection lies in a similarity threshold. By default, Git considers two files to be a rename if their content is at least 50% similar. This threshold can be adjusted, offering flexibility depending on the nature of your codebase and how frequently files are modified during a rename. For instance, if you often refactor code significantly while moving files, you might need to lower this threshold to help Git connect the dots. Conversely, a higher threshold might be useful in projects where minor changes could mistakenly trigger rename detection on unrelated files. Mastering this underlying mechanism is the first step in truly understanding how to REALLY show logs of renamed files with Git.

This intelligent approach means you don’t have to tell Git when you’ve renamed a file; it figures it out on its own. While tools like git mv exist to simplify the process by staging both the deletion and addition, they primarily serve as a convenience. Git’s ability to infer renames post-factum is a testament to its robust design for Git history tracking renames, ensuring that your commit history remains consistent and informative, even when file paths change dramatically. This feature is crucial for maintaining a clean and understandable project history, especially in large, collaborative environments.

The Essential git log --follow Command

When you want to trace the entire lineage of a single file, including all its name changes, the absolute indispensable command is git log --follow. This powerful flag instructs Git to not only show the commits affecting the specified file at its current path but also to chase its history backward through any renames it might have undergone. It’s the most direct and effective way to get a continuous Git file history, regardless of how many times the file has been moved or renamed within the repository.

To use it, simply execute git log --follow <filepath>. For example, if you’re looking for the history of a file currently named src/utils/helpers.js, but you suspect it was once lib/common.js, this command will reveal that entire journey. The output will display a chronological list of commits, each showing the changes made to that specific file, with an explicit notation when a rename occurred. This makes it incredibly easy to see when a file was introduced, modified, and subsequently renamed, offering unparalleled clarity into its evolution. It’s often the first command an experienced developer reaches for when encountering a file whose origin is unclear.

While incredibly useful, git log --follow has a specific scope: it works on a single file path at a time. If you need to see all renames across multiple files or within a broader set of commits, you’ll need to employ other strategies, which we’ll explore shortly. However, for a surgical look into one file’s complete history, including its identity transformations, there is no substitute for git log --follow. This command is a cornerstone for anyone serious about understanding how to REALLY show logs of renamed files with Git in a granular, file-specific manner.

While --follow is perfect for a single file, what if you want to inspect a range of commits and see all the renames that occurred within them? This is where git log -M (or --find-renames) combined with --name-status becomes invaluable. The -M flag enables Git’s rename detection for the log command, applying the default 50% similarity threshold. When used with --name-status, you get a concise output showing the status of each file in a commit, including ‘R’ for renamed files.

A typical command might look like: git log -M --name-status --oneline. This will show you a list of commits, and for each commit that involves a rename, you’ll see lines like R100 old/path/to/file.js new/path/to/file.js. The R100 indicates a rename with 100% similarity (or whatever similarity percentage Git calculated). This provides a quick overview of all renamed files across a series of commits, which is incredibly useful during code reviews or when trying to understand a large refactoring effort. According to Git’s official documentation, using -M is the primary way to enable detection of Question & Answer :

I’m relatively new to Git. I used Subversion (SVN) before.

I noticed that most of the graphical Git front-ends and IDE plugins don’t seem to be able to display the history of a file if the file has been renamed. When I use

git log --follow 

on the command line, I can see the whole log across renames.

According to Linus Torvalds (alternative link) the --follow switch is a “SVN noob” pleaser; serious Git users don’t use it:

--follow is a total hack, meant to just satisfy ex-SVN users who never knew anything about things like parenthood or nice revision graphs anyway.

It’s not totally fundamental, but the current implementation of “–follow” is really a quick preprocessing thing bolted onto the revision walking logic, rather than being anything really integral.

It literally was designed as a “SVN noob” pleaser, not as a “real git functionality” thing. The idea was that you’d get away from the (broken) mindset of thinking that renames matter in the big picture.

How do the hardcore Git users get the history of a file when it was renamed? What is the ‘real’ way to do this?

I think that the general drive behind Linus’ point is that—and take this with a pinch of salt—hardcore Git users don’t ever care about the history of a “file”. You put content in a Git repository because the content as a whole has a meaningful history.

A file rename is a small special case of “content” moving between paths. You might have a function that moves between files which a Git user might track down with the “pickaxe” functionality (e.g., log -S).

Other “path” changes include combining and splitting files; Git doesn’t really care which file you consider renamed and which one you consider copied (or renamed and deleted). It just tracks the complete content of your tree.

Git encourages “whole tree” thinking whereas many version control systems are very file-centric. This is why Git refers to “paths” more often than it refers to “filenames”.