gitlab-file

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

File Skill

文件操作技能

Repository file operations for GitLab using

glab api

raw endpoint calls.

使用

glab api

原始端点调用进行GitLab仓库文件操作。

Quick Reference

快速参考

Operation	Command Pattern	Risk
Get file info	`glab api projects/:id/repository/files/:path?ref=:branch`	-
Get raw content	`glab api projects/:id/repository/files/:path/raw?ref=:branch`	-
Get blame	`glab api projects/:id/repository/files/:path/blame?ref=:branch`	-
Create file	`glab api projects/:id/repository/files/:path -X POST -f ...`	⚠️
Update file	`glab api projects/:id/repository/files/:path -X PUT -f ...`	⚠️
Delete file	`glab api projects/:id/repository/files/:path -X DELETE -f ...`	⚠️⚠️

Risk Legend: - Safe | ⚠️ Caution | ⚠️⚠️ Warning | ⚠️⚠️⚠️ Danger

操作	命令模板	风险
获取文件信息	`glab api projects/:id/repository/files/:path?ref=:branch`	-
获取原始内容	`glab api projects/:id/repository/files/:path/raw?ref=:branch`	-
获取Blame信息	`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 ...`	⚠️⚠️

风险图例: - 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

When to Use This Skill

何时使用本技能

ALWAYS use when:

User wants to read file content from GitLab (not local)
User wants to create/update/delete files via GitLab API
User needs file blame information
User wants to download raw file content
User mentions "repository file", "blob", "raw content"

NEVER use when:

User wants to edit local files (use file editing tools)
User wants to search code (use gitlab-search)
User wants to browse repository tree (use gitlab-repo)
User wants to commit multiple files (use git locally)

务必在以下场景使用：

用户需要从GitLab（非本地）读取文件内容
用户需要通过GitLab API创建/更新/删除文件
用户需要文件Blame信息
用户需要下载原始文件内容
用户提及“仓库文件”、“blob”、“原始内容”

请勿在以下场景使用：

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

API Prerequisites

API 前置条件

Required Token Scopes:

api

Permissions:

Read files: Reporter+ (for private repos)
Create/update/delete files: Developer+ (need push access)

所需令牌权限范围:

api

权限:

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

URL Encoding

URL 编码

File paths must be URL-encoded. Slashes in paths become

%2F

bash

undefined

文件路径必须进行URL编码。路径中的斜杠会转换为

%2F

bash

undefined

src/main.py -> src%2Fmain.py

echo 'src/main.py' | jq -Rr @uri

Output: src%2Fmain.py

输出: src%2Fmain.py

undefined

undefined

Available Commands

可用命令

Get File Info (Base64 Encoded)

获取文件信息（Base64编码）

bash

undefined

bash

undefined

Get file metadata and content (base64)

获取文件元数据和内容（base64格式）

glab api "projects/123/repository/files/README.md?ref=main" --method GET

With URL-encoded path

使用URL编码后的路径

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

从提交SHA获取

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


**Response includes:**
- `file_name` - File name
- `file_path` - Full path
- `size` - File size in bytes
- `encoding` - Content encoding (base64)
- `content` - Base64-encoded content
- `content_sha256` - SHA256 hash
- `ref` - Branch/tag/commit
- `blob_id` - Blob SHA
- `commit_id` - Last commit SHA
- `last_commit_id` - Same as commit_id

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相同

Decode Base64 Content

解码Base64内容

bash

undefined

bash

undefined

Get and decode file content

获取并解码文件内容

glab api "projects/123/repository/files/README.md?ref=main" |
jq -r '.content' | base64 -d

undefined

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

undefined

Get Raw File Content

获取原始文件内容

bash

undefined

bash

undefined

Get raw file content (not base64)

获取原始文件内容（非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

undefined

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

undefined

Get File Blame

获取文件Blame信息

bash

undefined

bash

undefined

Get blame information

获取Blame信息

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

Parse blame output

解析Blame输出

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

undefined

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

undefined

Create File

创建文件

bash

undefined

bash

undefined

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"

glab api "projects/123/repository/files/$(echo 'docs/new-file.md' | jq -Rr @uri)" --method POST \ -f branch="main" \ -f content="# 新文件

内容此处" \ -f commit_message="添加新文档文件"

Create with base64 content

使用Base64内容创建文件

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"

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="添加配置文件"

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"

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="功能内容" \ -f commit_message="添加功能文件"

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="dev@example.com"
-f author_name="Developer"

undefined

glab api "projects/123/repository/files/script.sh" --method POST \ -f branch="main" \ -f content="#!/bin/bash
echo Hello" \ -f commit_message="添加脚本" \ -f author_email="dev@example.com" \ -f author_name="开发者"

undefined

Update File

更新文件

bash

undefined

bash

undefined

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"

glab api "projects/123/repository/files/README.md" --method PUT \ -f branch="main" \ -f content="# 更新后的README

新内容此处" \ -f commit_message="更新README"

Update with base64 (for binary or complex files)

使用Base64更新（适用于二进制或复杂文件）

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"

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 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"

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="重构应用模块"

Update with last known commit (for conflict detection)

使用已知最后提交ID更新（用于冲突检测）

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"

undefined

glab api "projects/123/repository/files/data.json" --method PUT \ -f branch="main" \ -f content="{ \"updated\": true }" \ -f commit_message="更新数据" \ -f last_commit_id="abc123def456"

undefined

Delete File

删除文件

bash

undefined

bash

undefined

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"

glab api "projects/123/repository/files/$(echo 'old-file.txt' | jq -Rr @uri)" --method DELETE \ -f branch="main" \ -f commit_message="移除已废弃文件"

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="dev@example.com"
-f author_name="Developer"

undefined

glab api "projects/123/repository/files/$(echo 'temp/test.txt' | jq -Rr @uri)" --method DELETE \ -f branch="main" \ -f commit_message="清理临时文件" \ -f author_email="dev@example.com" \ -f author_name="开发者"

undefined

File Operation Options

文件操作选项

Option	Type	Description
`branch`	string	Target branch (required for write ops)
`start_branch`	string	Source branch for new files
`content`	string	File content (plain text or base64)
`encoding`	string	Content encoding: `text` (default) or `base64`
`commit_message`	string	Commit message (required for write ops)
`author_email`	string	Custom author email
`author_name`	string	Custom author name
`last_commit_id`	string	Expected last commit (for conflict detection)

选项	类型	描述
`branch`	字符串	目标分支（写入操作必填）
`start_branch`	字符串	新文件的源分支
`content`	字符串	文件内容（纯文本或Base64格式）
`encoding`	字符串	内容编码格式： `text` （默认）或 `base64`
`commit_message`	字符串	提交信息（写入操作必填）
`author_email`	字符串	自定义作者邮箱
`author_name`	字符串	自定义作者名称
`last_commit_id`	字符串	预期的最后提交ID（用于冲突检测）

Common Workflows

常见工作流

Workflow 1: Download and View File

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

bash

undefined

bash

undefined

Get file content

获取文件内容

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

undefined

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

undefined

Workflow 2: Update Configuration File

工作流2：更新配置文件

bash

undefined

bash

undefined

1. Download current file

1. 下载当前文件

glab api "projects/123/repository/files/config.json/raw?ref=main" > config.json

2. Edit locally

2. 本地编辑

... make changes to config.json ...

... 对config.json进行修改 ...

3. Upload updated file

3. 上传更新后的文件

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"

undefined

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="更新配置"

undefined

Workflow 3: Create File on Feature Branch

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

bash

undefined

bash

undefined

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"

undefined

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="# 功能文档

详细信息此处..." \ -f commit_message="添加功能文档"

undefined

Workflow 4: Check File History via Blame

工作流4：通过Blame查看文件历史

bash

undefined

bash

undefined

Get blame info for a file

获取文件的Blame信息

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"'

undefined

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)行"'

undefined

Workflow 5: Batch Read Multiple Files

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

bash

undefined

bash

undefined

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

undefined

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

undefined

Workflow 6: Copy File Between Branches

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

bash

undefined

bash

undefined

1. Get file from source branch

1. 从源分支获取文件

content=$(glab api "projects/123/repository/files/config.json/raw?ref=develop")

2. Create/update on target branch

2. 在目标分支创建/更新文件

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"

undefined

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="从develop同步配置"

undefined

Troubleshooting

故障排除

Issue	Cause	Solution
404 Not Found	File doesn't exist	Verify path and branch
400 Path encoding	Slashes not encoded	Use `jq -Rr @uri` to encode
Binary content garbled	Not using base64	Use `/raw` endpoint or decode base64
Conflict on update	File changed	Use `last_commit_id` for optimistic locking
403 Forbidden	No push access	Need Developer+ role
Large file fails	Size limit	GitLab has file size limits

问题	原因	解决方案
404 未找到	文件不存在	验证路径和分支
400 路径编码错误	斜杠未编码	使用 `jq -Rr @uri` 进行编码
二进制内容乱码	未使用Base64	使用 `/raw` 端点或解码Base64
更新时冲突	文件已被修改	使用 `last_commit_id` 进行乐观锁检测
403 禁止访问	无推送权限	需要Developer及以上角色
大文件操作失败	超出大小限制	GitLab有文件大小限制

Size Limits

大小限制

Default max file size: 10 MB via API
Large files: Use Git LFS instead
Binary files: Always use base64 encoding

API默认最大文件大小：10 MB
大文件：使用Git LFS替代
二进制文件：始终使用Base64编码

Best Practices

最佳实践

URL-encode paths: Always encode file paths with slashes
Use base64 for binary: Encode binary files as base64
Meaningful commits: Write descriptive commit messages
Use feature branches: Don't commit directly to main for big changes
Check for conflicts: Use
```
last_commit_id
```
for critical updates

URL编码路径: 对包含斜杠的文件路径务必进行URL编码
二进制文件用Base64: 对二进制文件使用Base64编码
有意义的提交信息: 编写描述性的提交信息
使用功能分支: 不要直接向主分支提交大改动
冲突检测: 对关键更新使用
```
last_commit_id
```