批量删除远程Git Tag的实用脚本与避坑指南-代码聚汇网

批量删除远程Git Tag的实用脚本与避坑指南

子月二二·2026-09-03·阅读 22 GEO检测（免费）

Git批量删除远程Taggit ls-remote

|难度：普通|阅读约 31 分钟

1. 先说场景：我为什么要折腾"批量删除远程tag"

1.1 一次把tag打成灾难的经历

事情是这样的：我们的项目是个发布节奏比较快的服务端工程，每次发版都要打tag。上上迭代为了赶版本，我在测试环境一口气打了一排 v1.3.x 的tag，本来图省事，结果第三天产品说需求调整，这批版本全部作废，需要把对应tag从远程仓库清理干净。

我当时第一反应是手动删。执行 git push origin --delete tag名，删一个、确认一次、再删下一个。刚开始还行，删到第十几个就麻了——同样格式的命令重复敲了几十遍，不仅手指累，脑子也累。更要命的是仓库里还混着之前遗留的一堆 test_ 开头的tag，这次正好想一起清掉，结果数了数，接近五十个。

那个下午，我一边删一边想：这种纯重复操作，为什么不用脚本解决？于是放下鼠标，打开Git Bash，花二十分钟写了个批量删除远程tag的小脚本，跑完不到两分钟，几十个tag全部清干净。这篇文章就是记录我当时完整的排查路径、脚本思路和踩过的坑，希望对同样被一堆远程tag困扰的朋友有帮助。

1.2 为什么Git命令不能"一行搞定"

很多人第一反应可能是：Git不是有 git tag -d 吗？加个通配符不就行了？

这里必须拆开说清楚：git tag -d 删的是本地tag，不是远程仓库的tag。你本地删得再干净，git push 后远程的tags还在。更关键的是，Git原生并没有提供 git push --delete --pattern 这样的批量删除命令，你不能对着远程说"把 v1.3 开头的tag都给我删了"。

如果你项目用的是GitLab或者GitHub，网页上确实可以进仓库的Tags页面手动删除，但tag多了以后这个页面加载都卡，一个个点删除按钮同样费劲，而且容易误删。

所以结论很直接：批量删远程tag这件事，本质上是"批量构造并执行删除指令"的问题，那就该交给脚本。

1.3 这篇记录适合谁看

如果你满足下面几个条件，这篇内容对你应该是刚需：

日常开发在Windows上，终端用的是Git Bash，不是纯Linux环境
对Git命令有一定基础，但没怎么写过shell脚本
仓库里的tag数量已经多到不想在页面上手动翻
想找一个安全、可复用的方式，批量清理远程tag

不需要你会什么高深的bash语法，脚本总共三十行不到。真正难的不是脚本本身，而是搞清楚"远程tag在Git里到底是怎么存的"和"Windows环境下的几个隐藏坑"。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 删除远程tag这件事的本质：你其实是在"推"，不是"删"

2.1 远程tag看起来是"删"，实际是一次特殊的push

先说一个很多初学者容易想不通的点：远程tag不是一个独立在服务器上的实体文件，它在Git的refs体系里就是一条引用记录。

远程仓库的tag存储在服务器端的 refs/tags/ 目录下，比如你打了一个 v1.3.1 的tag，远端对应的就是 refs/tags/v1.3.1 这条引用。

删除远程tag的标准命令：

bash复制git push origin --delete v1.3.1

这条命令的本质是什么？是推送一个空的引用更新到远程，让远程仓库的 refs/tags/v1.3.1 这条引用消失。

理解了这一点，批量删除的思路就打开了：既然删除的本质是"构造一个更新远程refs的指令"，那我只要把远程所有 refs/tags/ 下的引用拉取出来，过滤出我要删的那些，然后逐个执行 git push origin --delete 就行了。

2.2 先搞清楚tag到底存在哪

在写脚本之前，我先做了一步探查。本地仓库里看tag，用的是 git tag -l，但这个命令默认只能看到本地存在的tags。如果我在别人的电脑上clone了一份仓库，或者远程tags是其他人推上去的，本地可能根本没有对应记录。

真正能反映远程tags全貌的命令是：

bash复制git ls-remote --tags origin

输出大概是这样的：

text复制1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0        refs/tags/v1.3.1
2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1        refs/tags/v1.3.1^{}
3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2        refs/tags/v1.3.2
4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3        refs/tags/test_20240601
...

第一列是tag指向的commit哈希，第二列是引用名，格式固定为 refs/tags/标签名。

这里就出现了一个非常经典的坑：同一行还有 refs/tags/v1.3.1^{} 这种带 ^{} 后缀的记录。这是Git的peeled表示法，意思是这个tag是一个附注tag（annotated tag），^{} 指向的是它真正关联的那个commit对象。普通的轻量tag（lightweight tag）则没有这行。

2.3 三种删除命令其实是等价的

我在排查的时候发现，网上关于删除远程tag的命令存在三种写法，很容易让人困惑：

命令写法	说明
`git push origin --delete tagName`	语义最清晰，推荐日常使用
`git push origin :refs/tags/tagName`	老式写法，推送空引用
`git push origin --delete refs/tags/tagName`	带完整refs路径，脚本里更精确

这三条命令作用一样。我在脚本里选的是第三种写法，因为后续循环处理时，直接从 ls-remote 输出的第二列取值，没那么多麻烦事。

注意：git push origin --delete tagName 里的 tagName 不带 refs/tags/ 前缀也能正确匹配，但如果你的tag名字比较特殊，比如带了斜杠（release/1.0），建议写成完整路径，避免歧义。

3. Windows环境准备：为什么是Git Bash，以及怎么设才不踩坑

3.1 为什么不用cmd或PowerShell，非要用Git Bash

我是在Windows上做开发的，第一反应自然是：脚本用bash写，那Windows下怎么跑？

Windows自带的cmd显然不行，它根本不认识bash语法。PowerShell虽然强大，但它的语法体系是另一套，我在Linux和Windows之间来回切的时候，不想维护两套脚本。

Git Bash是Git for Windows自带的一个环境，它本质上是一个模拟的bash环境，内置了Git命令，也支持 grep、awk、sed、tr 这些常用的Unix工具。这意味着：你在Linux上写的删tag脚本，在Windows的Git Bash里基本可以原样跑。

比WSL（Windows Subsystem for Linux）轻量，不用装整个Linux子系统；比Cygwin易用，装完Git就有了，不用额外配置环境变量。

3.2 安装和初始化的几件小事

Git Bash的安装不复杂，从官网下载Git for Windows，一路Next就行。但有两个小地方值得注意：

第一，安装过程中的"Adjusting your PATH environment"选项，建议选第二项 Git from the command line and also from 3rd-party software，这样不仅Git Bash能用，以后在cmd或终端里也能直接识别 git 命令，避免出现"系统提示无法将git项识别为cmdlet、函数、脚本文件或可运行程序的名称"这类报错。

第二，安装完成后，在任意目录右键选择"Git Bash Here"，进入终端先跑一下：

bash复制git --version

确认Git命令能正常执行，再检查一下你的仓库地址是不是HTTPS协议。如果是HTTP/HTTPS，脚本执行时每次push都可能需要输入账号密码，建议提前配置好凭据存储，否则脚本跑到一半卡在密码输入上，体验很糟糕。

3.3 脚本保存格式：Windows的换行符是最容易翻车的地方

这是我在Windows上用Git Bash写脚本碰到的第一个坑，也是网上问得最多的问题之一。

Windows下常见的文本换行是CRLF（也就是 \r\n），而Linux和Git Bash环境用的是LF（也就是 \n）。如果你用记事本或者某些保存默认格式为CRLF的编辑器写了脚本，拿到Git Bash里一跑，很可能会看到如下报错：

text复制$'\r': command not found

这个报错就是因为bash把每一行末尾的 \r 当成了命令的一部分。

解决办法有两个：

用VS Code打开脚本文件，右下角点击"CRLF"，切换成"LF"再保存
在Git Bash里用 sed -i 's/\r$//' delete-remote-tags.sh 把文件里的CRLF全部去掉

另外还有一个隐藏问题：如果你用 git ls-remote 的输出作为脚本循环输入，在Windows的Git Bash环境下，管道里传给下一级命令的内容行尾有时也会带 \r。这个坑我一开始没意识到，后面脚本跑起来才发现过滤不生效，这部分我在第5章会详细讲。

还有一个容易被忽略的点：git 的 core.autocrlf 配置。如果你在Windows下的仓库里创建脚本文件，默认可能是true，意味着git在checkout时会把LF自动转成CRLF。为了避免脚本被自动转换，建议脚本文件放在仓库目录之外，或者在仓库根目录加一个 .gitattributes 文件，明确标记脚本文件使用LF。

4. 脚本实操：从拉取远程tags到批量推送删除的完整路径

4.1 第一步：把远程tag完整拉出来看

写脚本之前，先把数据源摸清楚。我执行了：

bash复制git ls-remote --tags origin

实际操作中，输出可能非常长，尤其当仓库tag很多的时候。为了不想让终端被刷屏，可以直接先数个数：

bash复制git ls-remote --tags origin | wc -l

我看了一眼输出格式，基本上每个tag占一行（附注tag多一行 ^{}）。所以接下来脚本的第一步就是：获取这个列表，并且把 refs/tags/ 前缀剥掉，只留下纯粹的tag名字。

4.2 第二步：确定过滤规则，圈定删除范围

我当时的删除目标有两类：v1.3.x 开头的一批，以及所有 test_ 开头的tag。

批量操作最怕的不是删少了，而是误删。所以在脚本里，我用了case匹配来圈定范围，而不是直接全量删除。

一个简单的过滤例子：

bash复制git ls-remote --tags origin |
awk '{print $2}' |
sed 's#refs/tags/##; s/\^{}//' |
sort -u |
while read -r TAG; do
  case "$TAG" in
    v1.3.*|test_*) echo "将要删除: $TAG" ;;
  esac
done

这里的 v1.3.* 表示匹配以 v1.3. 开头的所有tag，test_* 同理。如果你用的是grep来筛选，记得加 -E 或者用锚点。比如：

bash复制grep -E '^(v1\.3\.|test_)'

4.3 第三步：循环推送删除，加输出验证

圈定范围之后，就是真正的删除动作了。循环体很简单：

bash复制git push origin --delete "$TAG"

但直接循环有个问题：万一中间某个tag删失败了，脚本不会告诉你它失败了，下一条照样执行，最后你根本不知道哪些成功了、哪些失败了。所以我给循环加了两层保险：

用 echo 打印当前正在处理的tag，让执行过程透明可见
检查 git push 的退出码，失败时打印警告，继续处理下一个

如果希望删除过程更温和一点，还可以在 git push 后面加参数 --quiet，减少输出，但我不建议，因为批量操作最好让每一步输出都清清楚楚。

4.4 完整脚本全文（可直接抄作业）

这是我最后定稿的脚本，保存为 delete-remote-tags.sh：

bash复制#!/bin/bash
# delete-remote-tags.sh
# 批量删除远程仓库中符合指定前缀的tag
# 用法: bash delete-remote-tags.sh [prefix...]
# 示例: bash delete-remote-tags.sh v1.3. test_

REMOTE="origin"
PATTERNS=("$@")
DRY_RUN=1   # 默认演练模式，设为0才真正执行删除

if [ "${#PATTERNS[@]}" -eq 0 ]; then
  echo "错误: 请指定要删除的tag前缀，例如: bash delete-remote-tags.sh v1.3. test_"
  exit 1
fi

echo "== 开始拉取远程tags =="
git ls-remote --tags "$REMOTE" |
  awk '{print $2}' |
  sed 's#refs/tags/##; s/\^{}//' |
  sort -u |
  while read -r TAG; do
    for PATTERN in "${PATTERNS[@]}"; do
      case "$TAG" in
        ${PATTERN}*)
          if [ "$DRY_RUN" = "1" ]; then
            echo "[dry-run] 将删除 $TAG"
          else
            echo "[deleting] $TAG"
            git push "$REMOTE" --delete "$TAG"
            if [ $? -ne 0 ]; then
              echo "[warning] 删除 $TAG 失败"
            else
              echo "[ok] $TAG 已删除"
            fi
          fi
          break
          ;;
      esac
    done
  done

if [ "$DRY_RUN" = "1" ]; then
  echo "== 当前为演练模式，未实际删除 =="
  echo "确认无误后，请先修改脚本内的 DRY_RUN=0，再执行一次"
fi

这段脚本有几个值得注意的设计点：

DRY_RUN 变量默认是1，也就是演练模式。第一次跑只会打印"将要删除哪些tag"，不会真正执行删除，防止手一抖删错
支持传入多个前缀参数，灵活适配多种清理场景
所有输出都带标记，方便查看进度
sort -u 去重，避免同一tag因为 ^{} 行被处理成两条删除请求

这里顺便说说为什么不用 xargs 直接一条命令搞定：

bash复制git ls-remote --tags origin | grep xxx | xargs -I {} git push origin --delete {}

网络上确实有这种写法，短是短，但问题在于：

没有隔离特殊字符，tag名字里如果包含 {} 这种，会出问题
不能先演练后执行，安全性差
中途出错不好定位

所以我不推荐，宁肯多写几行，也要把步骤拆开。删除是不可逆操作，shell命令越短，越要小心。

5. 实测排查记录：脚本报错的几个典型原因

5.1 原因一：从管道里取出来的tag名带着隐藏的\r

我第一次写完脚本，在Git Bash里跑演练模式，结果发现很多明明匹配前缀的tag没有被识别出来。排查了很久，最后用 cat -A 查看输出才发现，从 git ls-remote 管道里取出来的tag名，行尾多了一个看不见的 \r。

原因就是我在3.3节提到的Windows换行符问题。Git Bash虽然模拟了Unix环境，但在Windows的底层IO管道上，个别情况下输出会带上 \r。

解决方式是在 sed 处理中顺手把它剥掉：

bash复制sed 's#refs/tags/##; s/\^{}//; s/\r$//'

如果你的脚本是在Windows下用编辑器写成LF格式的，一般不会碰到这个问题。但如果你是在Windows下用记事本强行改了格式，或者从别的地方复制过来的脚本片段，这个坑非常容易出现。

5.2 原因二：`^{}` 这串幽灵后缀

这个坑在2.2节已经预埋了。附注tag在 ls-remote --tags 的输出里，除了正常行，还会多一行 refs/tags/xxx^{}。

如果脚本没有剥掉 ^{}，循环里就会试图执行：

bash复制git push origin --delete xxx^{}

然后收到长长的报错。虽然不致命，但会污染输出，让你分不清哪些tag真的删了、哪些是报错。

处理方式就是在 sed 里加一句：s/\^{}//。如果你用的标签全是轻量tag，可能遇不到这行，但仓库大了以后，没人能保证所有tag都是同一种类型，所以这个过滤一定要有。

5.3 原因三：tag被仓库管理平台保护，push被拒绝

脚本跑了一半，突然看到连续的 [warning]，提示删除失败。点开具体报错，发现GitLab返回了 remote rejected (protected tag hook declined)。

这是因为GitLab里开启了Protected Tags保护策略，某些tag（比如以 v 开头的正式版本）不允许随便删除。

这种情况下脚本本身没有错，是仓库权限控制的问题。处理方式有两个：

临时在GitLab的项目设置里，把受保护的tag规则调整或关闭，删完再恢复
把脚本的过滤模式调整一下，避开被保护的tag

这也提醒了我：批量删除操作，特别是涉及 release 或生产版本tag时，先确认有没有保护规则，不要拿脚本一把梭。

5.4 原因四：网络中断后不知道删到哪一步

方案调整后，全量执行删除时，公司网络突然抖了一下。脚本停下来，终端上最后一行停在某个tag名上。我心里一凉：它到底是删到一半断了，还是这个tag删失败了？

这个问题的根源在于：批量操作没有断点续传机制。

解决办法其实很简单：脚本设计成幂等的。所谓幂等，就是"重复执行不会产生额外副作用"。一个tag如果已经被删了，再次执行 git push origin --delete 会报错，但不会影响其他tag的删除。所以网络恢复后，直接把脚本再跑一遍就行。

如果实在心里没底，可以在删除前先保存一份远程tags列表：

bash复制git ls-remote --tags origin > remote-tags-backup.txt

万一某个tag被误删了，拿着这份清单你能对比出少了什么，然后根据记录的commit哈希重新推送恢复：

bash复制git update-ref refs/tags/v1.3.1 <commit-hash>

或者是如果有本地记录，直接用 git push origin v1.3.1 推回去。

5.5 为什么这些坑在官方文档里查不到

这些坑在 git push --help 里是查不到的，因为Git文档默认你是对着单个tag操作，根本不会考虑批量场景。而批量操作的坑大多是"多个命令组合在一起时才会触发"的组合问题，比如管道换行、refs列表格式、平台策略。

所以网上搜出来的相关内容很零散，有说用 xargs 的、有说用 for 循环的、有说用python脚本的。其实每个思路都对，关键是理解原理后再组装成适合自己的脚本，然后注意Windows环境特有的坑。

6. 给脚本加上安全阀：正式删之前的十秒钟

6.1 先用dry-run看名单，再取消DRY_RUN执行

我在脚本里默认把 DRY_RUN 设为1，这是一个刻意设计，不是偷懒。

删除tag不像删本地分支，本地分支删错了有些情况下还能找回来，远程tag一旦删除，影响范围是所有协作者。所以"先看名单，再执行"这个动作必须成为条件反射。

执行演练模式：

bash复制bash delete-remote-tags.sh v1.3. test_

你看到的输出应该是：

text复制== 开始拉取远程tags ==
[dry-run] 将删除 v1.3.1
[dry-run] 将删除 v1.3.2
...
== 当前为演练模式，未实际删除 ==

肉眼检查一遍名单，确认没有误伤，再把脚本里的 DRY_RUN=0，重新执行。

6.2 双保险：先把远程tags备份到本地文件

演练模式只能看名字，看不到每个tag对应的commit哈希。如果需要更稳妥的保险，建议在脚本执行之前，手动跑一次命令，把远程tags的完整清单保存下来：

bash复制git ls-remote --tags origin > remote-tags-backup.txt

这个备份文件里包含了每个tag对应的commit哈希，万一删错了，可以通过前面提到的 git update-ref 手工恢复。

虽然这个操作多花十秒钟，但它能让你在误删之后不慌。我把这条记在了脚本的注释里，提醒以后的自己。

6.3 从"删完就完"到"批量管理tag"的一点延展

脚本跑通了之后，我又顺手做了两个小改动，让这个脚本的适用范围更广：

第一，脚本支持多个前缀参数。这意味着以后想删 test_、tmp_、debug_ 开头的tag，一条命令全搞定：

bash复制bash delete-remote-tags.sh test_ tmp_ debug_

第二，把过滤条件改成"保留"模式。有时候我不是想删前缀匹配的tag，而是想删掉"除了正式版本以外"的所有tag。这个用case里的反向匹配也能实现，不过我更建议改成白名单思路，保留哪些tag、删除其余，这样的策略更安全。

另外，如果你的团队配合CI使用，这个脚本也可以放进流水线的维护任务里，定期清理过期tag。只是到这一步，一定要把 DRY_RUN 机制保留下来，最好再加一个 CONFIRM 二次确认变量，比如执行时需要手动传入 CONFIRM=yes，才能继续。

我在实际使用中最大的体会是：这种批量删除脚本，第一次跑通花二十分钟，之后每次用只花两分钟，但省下的时间远不止这些。以前看到远程tag列表里一堆废弃tag，总是忍着不想动，现在每个迭代尾期顺手跑一遍脚本，几秒钟清理干净，整个仓库的历史也清爽很多。

如果你也被同一堆远程tag困扰着，按这个思路写一个自己的脚本就行。注意先跑dry-run，看看名单再执行。