---
title: "Renaming files"
slug: "renaming-files"
updated: 2024-12-12T06:17:46Z
published: 2024-12-12T06:17:46Z
canonical: "learn.allspice.io/renaming-files"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://learn.allspice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Renaming files

## Git Renaming vs. Non-Git Renaming and Fixing Unrecognized Renames

When working with Git, renaming files can be tracked in two ways:

**Git Renaming**: Using `git mv` or a Git-aware tool to rename a file ensures Git tracks the rename as part of the file's history. This preserves all previous changes and makes it easier to trace the file's evolution.

**Non-Git Renaming**: Renaming a file directly in the file system (outside Git) causes Git to interpret the change as a deletion of the original file and the creation of a new one, breaking the history link. This can confuse some applications that rely on Git's rename tracking.

---

## Fixing Unrecognized Renames in Git

If a file was renamed without Git recognizing it, you can fix it:

1. **Stage the Changes** Add both the "deleted" file and the "new" file to the staging area:

```
git add old_filename new_filename
```
2. **Manually Mark the Rename** Move the new file back to the original name temporarily and then rename it using Git:

```
mv new_filename old_filename
git mv old_filename new_filename
```
3. **Commit the Rename** Commit the changes to properly record the rename and preserve history:

```
git commit -m "Renamed old_filename to new_filename"
```

---

## Retrospective Detection of Renames

If the rename has already been committed as a delete and an add, Git can detect it retrospectively based on content similarity during operations like `git log` or `git diff`:

- Use `--follow` with `git log` to trace history across renames:

```
git log --follow new_filename
```
- Use `-M` during `git diff` to detect renames:

```
git diff -M
```

---

## Automating Rename Detection

To make Git more aggressive in detecting renames for diffs and logs:

```
git config diff.renames true
```

This setting helps Git interpret renames based on content similarity but does not retroactively rewrite history. Always use `git mv` for renaming when possible to avoid these issues.