gitlab-file

文件技能

使用 glab api 原始端点调用，对 GitLab 执行仓库文件操作。

快速参考

操作	命令模式	风险
获取文件信息	glab api projects/:id/repository/files/:path?ref=:branch	-
获取原始内容	glab api projects/:id/repository/files/:path/raw?ref=:branch	-
获取代码追责信息	glab api projects/:id/repository/files/:path/blame?ref=:branch	-
创建文件	glab api projects/:id/repository/files/:path -X POST -f ...	⚠️
更新文件	glab api projects/:id/repository/files/:path -X PUT -f ...	⚠️
删除文件	glab api projects/:id/repository/files/:path -X DELETE -f ...	⚠️⚠️

风险说明：- 安全 | ⚠️ 谨慎 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

何时使用此技能

始终在以下情况使用：

• 用户想要读取 GitLab 上（而非本地）的文件内容
• 用户想要通过 GitLab API 创建、更新或删除文件
• 用户需要文件的代码追责信息
• 用户想要下载原始文件内容
• 用户提到“仓库文件”“blob”“原始内容”

绝不要在以下情况使用：

• 用户想要编辑本地文件（使用文件编辑工具）
• 用户想要搜索代码（使用 gitlab-search）
• 用户想要浏览仓库树（使用 gitlab-repo）
• 用户想要提交多个文件（使用本地 git）

API 前提条件

所需令牌作用域： api

权限：

• 读取文件：Reporter 及以上（适用于私有仓库）
• 创建、更新、删除文件：Developer 及以上（需要推送权限）

URL 编码

文件路径必须进行 URL 编码。路径中的斜杠应转换为 %2F：

# src/main.py -> src%2Fmain.py
echo 'src/main.py' | jq -Rr @uri
# Output: src%2Fmain.py

可用命令

获取文件信息（Base64 编码）

# Get file metadata and content (base64)
glab api "projects/123/repository/files/README.md?ref=main" --method GET

# With URL-encoded path
glab api "projects/123/repository/files/$(echo 'src/main.py' | jq -Rr @uri)?ref=main"

# From specific branch
glab api "projects/123/repository/files/config.json?ref=develop" --method GET

# From tag
glab api "projects/123/repository/files/version.txt?ref=v1.0.0" --method GET

# From commit SHA
glab api "projects/123/repository/files/app.py?ref=abc123" --method GET

响应包含：

• file_name - 文件名
• file_path - 完整路径
• size - 文件大小（字节）
• encoding - 内容编码（base64）
• content - Base64 编码的内容
• content_sha256 - SHA256 哈希值
• ref - 分支、标签或提交
• blob_id - Blob SHA
• commit_id - 上次提交的 SHA
• last_commit_id - 与 commit_id 相同

解码 Base64 内容

# Get and decode file content
glab api "projects/123/repository/files/README.md?ref=main" | \
  jq -r '.content' | base64 -d

获取原始文件内容

# Get raw file content (not base64)
glab api "projects/123/repository/files/README.md/raw?ref=main" --method GET

# With encoded path
glab api "projects/123/repository/files/$(echo 'src/app.py' | jq -Rr @uri)/raw?ref=main"

# Binary file (save to file)
glab api "projects/123/repository/files/$(echo 'images/logo.png' | jq -Rr @uri)/raw?ref=main" > logo.png

获取文件代码追责信息

# Get blame information
glab api "projects/123/repository/files/$(echo 'src/main.py' | jq -Rr @uri)/blame?ref=main" --method GET

# Parse blame output
glab api "projects/123/repository/files/$(echo 'src/main.py' | jq -Rr @uri)/blame?ref=main" | \
  jq -r '.[] | "\(.commit.author_name): lines \(.lines | length)"'

创建文件

# Create new file with content
glab api "projects/123/repository/files/$(echo 'docs/new-file.md' | jq -Rr @uri)" --method POST \
  -f branch="main" \
  -f content="# New File\n\nContent here" \
  -f commit_message="Add new documentation file"

# Create with base64 content
glab api "projects/123/repository/files/$(echo 'data/config.json' | jq -Rr @uri)" --method POST \
  -f branch="main" \
  -f content="$(cat config.json | base64)" \
  -f encoding="base64" \
  -f commit_message="Add configuration file"

# Create on new branch
glab api "projects/123/repository/files/$(echo 'feature/new.txt' | jq -Rr @uri)" --method POST \
  -f branch="feature-branch" \
  -f start_branch="main" \
  -f content="Feature content" \
  -f commit_message="Add feature file"

# Create with author info
glab api "projects/123/repository/files/script.sh" --method POST \
  -f branch="main" \
  -f content="#!/bin/bash\necho Hello" \
  -f commit_message="Add script" \
  -f author_email="[email protected]" \
  -f author_name="Developer"

更新文件

# Update file content
glab api "projects/123/repository/files/README.md" --method PUT \
  -f branch="main" \
  -f content="# Updated README\n\nNew content here" \
  -f commit_message="Update README"

# Update with base64 (for binary or complex files)
glab api "projects/123/repository/files/$(echo 'config/settings.json' | jq -Rr @uri)" --method PUT \
  -f branch="main" \
  -f content="$(cat settings.json | base64)" \
  -f encoding="base64" \
  -f commit_message="Update settings"

# Update on feature branch
glab api "projects/123/repository/files/src%2Fapp.py" --method PUT \
  -f branch="feature-update" \
  -f content="$(cat app.py | base64)" \
  -f encoding="base64" \
  -f commit_message="Refactor app module"

# Update with last known commit (for conflict detection)
glab api "projects/123/repository/files/data.json" --method PUT \
  -f branch="main" \
  -f content="{ \"updated\": true }" \
  -f commit_message="Update data" \
  -f last_commit_id="abc123def456"

删除文件

# Delete file
glab api "projects/123/repository/files/$(echo 'old-file.txt' | jq -Rr @uri)" --method DELETE \
  -f branch="main" \
  -f commit_message="Remove deprecated file"

# Delete with author info
glab api "projects/123/repository/files/$(echo 'temp/test.txt' | jq -Rr @uri)" --method DELETE \
  -f branch="main" \
  -f commit_message="Clean up temp files" \
  -f author_email="[email protected]" \
  -f author_name="Developer"

文件操作选项

选项	类型	说明
branch	string	目标分支（写入操作必需）
start_branch	string	新建文件时的源分支
content	string	文件内容（纯文本或 base64）
encoding	string	内容编码：text（默认）或 base64
commit_message	string	提交消息（写入操作必需）
author_email	string	自定义作者邮箱
author_name	string	自定义作者姓名
last_commit_id	string	预期的上次提交（用于冲突检测）

常见工作流

工作流 1：下载并查看文件

# Get file content
glab api "projects/123/repository/files/$(echo 'config/app.yml' | jq -Rr @uri)/raw?ref=main"

工作流 2：更新配置文件

# 1. Download current file
glab api "projects/123/repository/files/config.json/raw?ref=main" > config.json

# 2. Edit locally
# ... make changes to config.json ...

# 3. Upload updated file
glab api "projects/123/repository/files/config.json" --method PUT \
  -f branch="main" \
  -f content="$(cat config.json | base64)" \
  -f encoding="base64" \
  -f commit_message="Update configuration"

工作流 3：在功能分支上创建文件

# Create new file on new branch
glab api "projects/123/repository/files/$(echo 'docs/feature.md' | jq -Rr @uri)" --method POST \
  -f branch="feature-docs" \
  -f start_branch="main" \
  -f content="# Feature Documentation\n\nDetails here..." \
  -f commit_message="Add feature documentation"

工作流 4：通过代码追责信息检查文件历史

# Get blame info for a file
glab api "projects/123/repository/files/$(echo 'src/critical.py' | jq -Rr @uri)/blame?ref=main" | \
  jq -r '.[] | "\(.commit.short_id) \(.commit.author_name): \(.lines | length) lines"'

工作流 5：批量读取多个文件

# Read multiple files
for file in "README.md" "package.json" "Dockerfile"; do
  echo "=== $file ==="
  glab api "projects/123/repository/files/$(echo "$file" | jq -Rr @uri)/raw?ref=main"
  echo ""
done

工作流 6：在分支之间复制文件

# 1. Get file from source branch
content=$(glab api "projects/123/repository/files/config.json/raw?ref=develop")

# 2. Create/update on target branch
echo "$content" | base64 > /tmp/content.b64
glab api "projects/123/repository/files/config.json" --method PUT \
  -f branch="main" \
  -f content="$(cat /tmp/content.b64)" \
  -f encoding="base64" \
  -f commit_message="Sync config from develop"

故障排除

问题	原因	解决方案
404 Not Found	文件不存在	确认路径和分支
400 Path encoding	斜杠未编码	使用 jq -Rr @uri 进行编码
二进制内容乱码	未使用 base64	使用 /raw 端点或解码 base64
更新时发生冲突	文件已更改	使用 last_commit_id 进行乐观锁定
403 Forbidden	没有推送权限	需要 Developer 及以上角色
大文件操作失败	大小限制	GitLab 对文件大小有限制

大小限制

• 通过 API 操作时，默认最大文件大小：10 MB
• 大文件：改用 Git LFS
• 二进制文件：始终使用 base64 编码

最佳实践

1. 对路径进行 URL 编码：始终对包含斜杠的文件路径进行编码
2. 二进制文件使用 base64：将二进制文件编码为 base64
3. 提交信息要有意义：编写描述清晰的提交信息
4. 使用功能分支：进行重大更改时，不要直接提交到 main
5. 检查冲突：对于关键更新，请使用 last_commit_id

相关文档

• API 辅助工具
• 安全措施
• 快速参考
• GitLab 仓库文件 API