glab-repo

glab repo

处理 GitLab 仓库和项目。

glab 将 API 返回的仓库 URL 传递给 Git 前，会先验证这些 URL。支持的 URL 方案和类 scp 的 SSH 语法均可接受；类似选项的字符串、远程助手传输方式、空白字符和控制字符都会被拒绝。如果克隆、派生或远程操作因远程 URL 无效而失败，请检查可信的项目／主机元数据，而不要绕过验证或直接将该字符串交给 Git。

快速开始

# Clone a repository
glab repo clone group/project

# Clone the project's wiki repository
glab repo clone --wiki group/project

# Create new repository
glab repo create my-new-project --public

# Fork a repository
glab repo fork upstream/project

# View repository details
glab repo view

# Add a Git remote from a GitLab project reference
glab repo remote add group/project --name upstream

# Prune local branches whose MRs have been merged
glab repo prune --dry-run
glab repo prune --yes

# Search for repositories
glab repo search "keyword"

常见工作流

启动新项目

如果省略 --private、--internal 和 --public，GitLab 会使用实例的默认项目可见性。创建项目时，请明确指定所需的可见性。

1. 创建仓库：

   glab repo create my-project \
     --public \
     --description "My awesome project"
   
   # Create with README
   glab repo create my-project \
     --public \
     --readme
   

   注意： glab repo create --readme 会克隆新创建的仓库，而不是使用 git init，以确保本地副本干净且包含初始 README。

   glab repo create --skipGitInit 会创建远程项目，但不会提示初始化本地目录。如果当前目录尚未是 Git 仓库，glab 也会跳过添加远程仓库，而不会在远程仓库创建成功后发出误导性的 fatal: not a git repository 警告。

   包含嵌套组的路径会保留完整命名空间。例如，glab repo create group/subgroup/my-project 会在 group/subgroup 下创建 my-project，而不只是创建在最后一级子组下。

2. 在本地克隆（如果未使用 --readme）：

   glab repo clone my-username/my-project
   cd my-project
   

   若只克隆 GitLab Wiki，请在一个项目引用上使用 --wiki。它不能与面向整个组的 --group 克隆组合使用；如果项目的 Wiki 已禁用，则会明确报错。

   glab repo clone --wiki group/project
   

   如果 SSH 配置将 gitlab.com 映射到官方的 altssh.gitlab.com 端点，该配置会被识别为 GitLab.com，而不是单独的自托管主机。

   对于包含端口的自托管主机，glab 会使用完整主机名（含端口）查找子文件夹配置。如果仓库解析到了错误的 API 主机，或未找到已配置的子文件夹，请确认 glab config path 中配置文件里的主机键包含端口。

3. 使用内容初始化：

   echo "# My Project" > README.md
   git add README.md
   git commit -m "Initial commit"
   git push -u origin main
   

派生工作流

1. 派生上游仓库：

   glab repo fork upstream-group/project
   

2. 克隆你的派生仓库：

   glab repo clone my-username/project
   cd project
   

3. 添加上游远程仓库：

   glab repo remote add upstream-group/project --name upstream
   

   glab repo remote add <namespace/project> 会解析 GitLab 项目引用，并添加相应的 Git 远程 URL。默认远程名称是路径的第一个组成部分（示例中的 upstream-group）；可使用 --name / -n 覆盖。使用 --protocol ssh|https / -p 可覆盖 git_protocol 配置。

   glab repo remote add alice/my-project
   glab repo remote add alice/my-project --name upstream
   glab repo remote add group/subgroup/my-project --protocol ssh
   

4. 保持派生仓库同步：

   git fetch upstream
   git merge upstream/main
   

自动同步：

使用此技能在 scripts/ 下附带的同步脚本，只需一条命令即可更新 派生仓库（以下路径均相对于技能自身的目录）：

scripts/sync-fork.sh main
scripts/sync-fork.sh develop upstream

此脚本会自动：获取 → 合并 → 推送到 origin。

仓库管理

查看仓库信息：

glab repo view
glab repo view group/project  # Specific repo
glab repo view --web          # Open in browser

更新仓库设置：

glab repo update \
  --description "Updated description" \
  --default-branch develop

归档仓库：

glab repo archive download main  # Downloads .tar.gz
glab repo archive download main --format zip

转移到新的命名空间：

glab repo transfer my-project --target-namespace new-group

删除仓库：

glab repo delete group/project

清理本地分支

glab repo prune 会删除 GitLab 合并请求已合并的本地 Git 分支。它绝不会删除 GitLab 上的远程分支，并会跳过受保护的分支、默认分支以及当前检出的分支。

# Preview branches that would be deleted
glab repo prune --dry-run

# Delete branches after confirmation
glab repo prune

# Delete without confirmation after reviewing the dry run
glab repo prune --yes

# Exclude additional branches by exact name or glob; comma-separate or repeat
glab repo prune --exclude wip-*,demo-branch

# Faster local-Git detection; misses squash/rebase merges that are not fast-forward ancestry
glab repo prune --merged

为确保准确性，建议使用默认的 GitLab 支持模式：它会查询每个本地分支对应的合并请求，并且比单纯的 git branch --merged 更妥善地处理压缩合并和变基合并的情况。只有在可以接受更快但仅支持快进检查的情况下，才使用 --merged。

成员管理

列出协作者：

glab repo members list

添加成员：

glab repo members add @username --access-level maintainer

移除成员：

glab repo members remove @username

更新成员访问权限：

glab repo members update @username --access-level developer

批量操作

克隆组中的所有仓库：

glab repo clone -g my-group

# Skip selected subgroups and their descendants across every page
glab repo clone -g my-group --exclude-subgroup domain/backend,archived --paginate

--exclude-subgroup 接受相对于 --group 的子组路径，而非数字子组 ID。可重复使用此标志，或用逗号分隔路径。匹配时不区分大小写，会去除首尾斜杠，接受带有完整组路径前缀的路径，并遵循路径边界（team 不会排除 team-other）。数字格式的 --group ID 会在筛选前解析为完整路径。来自其他命名空间的共享项目不受影响。默认会包含子组；排除项会在获取项目后、克隆前筛选项目。如果获取的项目全部被排除，命令会失败并显示 “No projects left to clone” 消息。

搜索并克隆：

glab repo search "api" --per-page 10
# Then clone specific result
glab repo clone group/api-project

列出你的仓库：

glab repo list
glab repo list --member          # Only where you're a member
glab repo list --mine            # Only repos you own

故障排除

克隆因权限错误而失败：

• 确认你有访问权限：glab repo view group/project
• 检查身份验证状态：glab auth status
• 对于私有仓库，确保你已使用正确的账户登录

Fork 操作失败：

• 检查你的命名空间中是否已存在此 Fork
• 确认你有 Fork 权限（某些仓库已禁用 Fork）
• 尝试指定命名空间：glab repo fork --fork-path username/new-name

转移失败：

• 确认你拥有所有者或维护者访问权限
• 检查目标命名空间是否存在，以及你是否有创建权限
• 某些项目可能启用了转移保护

克隆组失败：

• 确认组存在且你有访问权限
• 检查磁盘空间是否充足
• 大型组可能会超时——请改为克隆特定仓库

相关技能

身份验证和访问：

• 登录和身份验证设置请参阅 glab-auth
• SSH 密钥管理请参阅 glab-ssh-key
• 部署身份验证请参阅 glab-deploy-key

项目配置：

• CLI 默认值和设置请参阅 glab-config
• CI/CD 变量请参阅 glab-variable

Fork 同步：

• 脚本：scripts/sync-fork.sh 可自动同步上游

结构化输出

glab repo contributors 支持使用 --output json / -F json 生成结构化输出，适用于 Agent 自动化。

# List contributors with JSON output
glab repo contributors --output json
glab repo contributors -F json

命令参考

完整命令文档和所有标志请参阅 references/commands.md。

可用命令：

• clone - 克隆仓库或组
• create - 创建新项目
• fork - Fork 仓库
• view - 查看项目详情
• update - 更新项目设置
• delete - 删除项目
• search - 搜索项目
• list - 列出仓库
• transfer - 转移到新的命名空间
• archive - 下载仓库归档
• contributors - 列出贡献者
• members - 管理项目成员
• mirror - 配置仓库镜像
• remote - 使用 GitLab 项目引用管理 Git 远程仓库
• prune - 删除其 GitLab 合并请求已合并的本地分支
• publish - 发布项目资源