git mv 移动或重命名文件,并把这次变更直接写进暂存区。Git 本身靠内容相似度识别重命名,所以这条命令本质上是「系统 mv + git add + git rm」的便捷封装。

本文列出 git mv 的常用参数,说明大小写重命名、跨目录移动和跟踪历史的注意事项。

ℹ️
关于本系列
本文是《Git 使用教程》按命令拆分的第 17 / 28 篇,全部收录在 Git 栏目。参数表列的是日常高频项,并非穷举;想看某个命令的完整参数,用 git mv -h 看精简列表、git help mv 看完整手册。示例以 Git 2.56.0 为准。

一、命令语法

先看语法骨架,再对照下一节的参数表。<占位> 表示必填值,实际输入时不要带尖括号;[...] 表示可选项,-- 用来分隔选项与路径。

bash语法
git mv [<options>] <source>... <destination>

二、参数逐项详解

下表按用途列出 git mv 的常用参数,每项都注明了「它到底改变了什么」。

参数作用
<source> <destination>源文件/目录与目标;多个源文件时目标必须是目录
-f / --force目标已存在时强制覆盖,或源文件有本地改动时强制移动
-n / --dry-run只演练,不真的移动
-v / --verbose打印每一条改名明细
-k跳过会导致错误(如目标已存在)的操作,继续处理其它文件
--分隔选项与路径

三、常用示例

重命名与移动目录

bash重命名与移动目录
git mv src/old-name.js src/new-name.js
git mv src/utils/ src/helpers/
git mv -v README.md docs/README.md

只改大小写(Linux / macOS 常见坑)

bash只改大小写(Linux / macOS 常见坑)
git mv -f Readme.md README.md
# 若文件系统不区分大小写,可借助临时名
git mv Readme.md readme.tmp && git mv readme.tmp README.md

先看再动

bash先看再动
git mv -n src/legacy/ src/archive/
git status -s

四、注意事项

不用 git mv 也能被识别为重命名: 直接改文件名再 git add -A,Git 同样会按内容相似度判定为 R(rename)。想让历史一路跟下去,查看时加 git log --follow -- <新路径>。
⚠️
同一次提交里别「又改内容又改路径」
改动幅度过大时相似度检测会失效,历史里会被记成「删除 + 新增」。需要保留重命名记录,就把移动和内容修改拆成两次提交。

五、小结

git mv 参数很少,实际只要记住 -f(覆盖/强制)和 -n(预演)。真正值得注意的是跨平台大小写问题和「重命名与内容改动拆开提交」这个习惯。

本系列共 28 篇,一个命令一篇,完整目录见 Git 栏目。下一篇:git branch 命令参数详解。