git river

git-river 是一款旨在简化处理大量GitHub和GitLab项目以及涉及从“上游”仓库拉取更改并推送到“下游”仓库的“分支”工作流程的工具。

git-river 将管理您配置的“工作空间”路径，将仓库以树状结构克隆到该目录中，该结构按域名、项目命名空间和项目名称组织。

$ tree ~/workspace
~/workspace
├── github.com
│   └── datto
│       └── git-river
└── gitlab.com
    └── datto
        └── git-river

链接

• 源代码
• 包

安装

git-river 需要 Python 3.9 或更高版本。

pip3 install git-river

使用方法

运行 git-river <子命令>。Git 内置别名也允许您运行 git river。

在您可以使用 git-river 之前，您必须通过运行 git-river init PATH 或设置 GIT_RIVER_WORKSPACE 环境变量来配置工作空间路径。这应该指向一个目录，git-river 可以将其用作将 Git 仓库克隆到其中的目录。

几个命令会尝试发现各种名称，通常都有一个选项标志来覆盖发现。

• “上游”远程仓库是存在的第一个 upstream 或 origin。可以使用 --upstream 覆盖。
• “下游”远程仓库是存在的第一个 downstream。可以使用 --downstream 覆盖。
• “主线”分支是存在的第一个 main 或 master。可以使用 --mainline 覆盖。

子命令

• git river clone URL... 将仓库克隆到工作路径。

• git river config 管理配置文件。

  • git river config display 以 JSON 格式打印加载的配置。凭证已被隐藏。
  • git river config init 创建初始配置文件。
  • git river config workspace 打印工作路径。

• git river forge 管理由 GitHub 和 GitLab 列出的仓库。

  • git river forge 执行 clone + archived + configure + remotes 子命令。
  • git river forge clone 克隆仓库。
  • git river forge configure 设置 git 配置选项。
  • git river forge fetch 获取每个 git 远程仓库。
  • git river forge list 显示将要克隆的远程仓库。
  • git river forge remotes 设置 upstream+downstream 或 origin 远程仓库。
  • git river forge tidy 删除合并到主线分支的分支。
  • git river forge archived 列出本地存在的归档仓库。

• git river 还提供了一些在当前目录的仓库上工作的“松散”子命令，大多数与 forge 子命令的功能相匹配。

  • git river fetch 获取所有 git 远程仓库。
  • git river merge 创建所有 feature/* 分支的合并结果。
  • git river tidy 删除合并到主线分支的分支。
  • git river restart 将当前分支从上游远程仓库的主线分支重新基。

配置

配置是从 ~/.config/git-river/config.json 读取的 JSON 对象。运行 git-river config init 创建示例配置文件。

• path - 用来作为“工作区”的目录路径。
• forges - 一个 forge 映射。

Forge 有以下选项。只有 type 是必需的 - 默认配置是使用不带身份验证的主要公共 GitHub 或 GitLab 域。

• type (必需) - 实例的类型，要么是 github，要么是 gitlab。
• base_url (可选) - 实例的基础 URL。不应包含尾随斜杠。
  • GitHub 实例的默认值为 https://api.github.com。
  • GitLab 实例的默认值为 https://gitlab.com。
• login_or_token (可选，仅 GitHub) - 认证令牌。
• private_token (可选，仅 GitLab) - 认证令牌。
• gitconfig (默认: {}) - 要在仓库上设置的 git 配置选项的键值映射。
• groups (默认: []) - 包含特定组的仓库。
• users (默认: []) - 包含特定用户的仓库。
• self (默认: true) - 自动包含认证用户的仓库。

示例

{
  "workspace": "~/Development",
  "forges": {
    "gitlab": {
      "type": "gitlab",
      "base_url": "https://gitlab.com",
      "private_token": "...",
      "groups": [],
      "users": [],
      "self": true,
      "gitconfig": {
        "user.email": "user+gitlab@example.invalid"
      }
    },
    "github": {
      "type": "github",
      "login_or_token": "...",
      "groups": [],
      "users": [],
      "gitconfig": {
        "user.email": "user+github@example.invalid"
      }
    }
  }
}

开发

Poetry 用于开发、构建和打包 git-river。Poetry 的 文档 描述了如何在您的操作系统上安装它。安装后，使用 poetry install 创建包含 git-river 及其依赖项的虚拟环境。

然后，您可以使用 poetry run git-river 运行 CLI 的本地版本。

代码使用 black 格式化，使用 poetry run black git_river 运行。

使用 mypy 检查类型，使用 poetry run mypy git_river 运行。

测试使用pytest编写，使用poetry run pytest运行。

# Download the project and install dependencies
git clone https://github.com/datto/git-river.git
cd git-river
poetry install

# Use the local version of the CLI
poetry run git-river ...

# Test, lint and format code
poetry run black git_river
poetry run mypy git_river
poetry run pytest

许可证

根据Mozilla公共许可证第2.0版许可。

版权所有：Datto, Inc.

由Sam Clements编写。