git-next

基于主干的开发管理器。

这是一种源代码控制分支模式，开发者在名为“主干”的单个分支上协同工作，采用文档化的技术抵制创建其他长期开发分支的压力。因此，他们避免了合并地狱，不会破坏构建，并且生活得非常快乐。- 来源

• 状态：BETA - 内部测试

git-next是一个结合了服务器和命令行工具的应用，它允许基于主干的开发工作流程，其中每个提交都必须通过CI（持续集成）才能被包含到主分支中。

功能

• 允许强制要求每个提交在包含到主分支之前必须通过CI管道
• 提供服务器组件以管理基于主干的开发过程
• 通过防止未经测试的更改被添加到主分支来确保代码库的一致性和高质量
• 要求每个提交使用约定提交格式。

请参阅行为了解我们是如何做到这一点的。

先决条件

• Rust 1.76.0或更高版本 - https://rust-lang.net.cn
• pgk-config
• libssl-dev
• libdbus-1-dev (ubuntu/debian)
• dbus-devel (fedora)

有关它们的配置方式，请参阅.cargo/config.toml。

安装

您可以从https://crates.io/安装git-next。

cargo install git-next

如果您使用mise

mise use -g cargo:git-next

或者您可以在克隆后从源代码安装git-next。

cargo install --path crates/cli

路线图

• 命令行界面
• 服务器
• 通知 - 在需要干预时通知用户（例如，需要rebase）
• 文本用户界面概览
• Web用户界面概览

分支名称

git-next使用三个分支，main、next和dev，尽管它们不需要有这些名称。在文档中我们将使用这些名称，但每个仓库必须指定每个要使用的分支的名称，即使它们恰好有这些相同的名称。

配置

• 要使用 main、next 和 dev 分支，必须在仓库本身的 .git-next.toml 文件或服务器配置文件 git-next-server.toml 中指定。详细信息请见下文。
• CI 检查应该配置为在 next 分支被 push 时运行。
• dev 分支 必须 将 main 分支作为其祖先。
• next 分支 必须 将 main 分支作为其祖先。

服务器

服务器通过 git-next-server.toml 文件进行配置。

listen

服务器应监听来自每个 forge 的 webhook 通知。

[listen]
http = { addr = "0.0.0.0", port = 8080 }
url = "https://127.0.0.1:8080"

http

服务器需要能够接收来自您的 forge 的 webhook 通知（例如，github.com）。您可以通过任何适合您环境的方法来完成此操作，例如 ngrok 或来自可以路由流量到运行 git-next 服务器的机器的 web 服务器的反向代理。

指定服务器应监听传入 webhooks 的地址和端口号。这是反向代理应路由流量的地址和端口。

• addr - 服务器应绑定的 IP 地址
• port - 服务器应绑定的 IP 端口

url

forge 应发送 webhooks 的 HTTPS URL。

您的 forge 需要知道它们应将 webhooks 路由到何处。这应该是一个对 forge 可访问的地址。因此，对于 github.com，它需要是一个公开可访问的 HTTPS URL。对于自托管的 forge，例如 ForgeJo，在您的网络中，它只需要从运行 forge 的服务器上可访问。

shout

服务器应在需要手动干预时通知用户。

[shout]
desktop = true

[shout.webhook]
url = "https//127.0.0.1:9090"
secret = "secret-password"

[shout.email]
from = "[email protected]"
to = "[email protected]"

[shout.email.smtp]
hostname = "smtp.example.com"
username = "[email protected]"
password = "MySecretEmailPassword42"

desktop

当指定为 true 时，某些事件将发送桌面通知。

webhook

对于某些事件将发送 POST 请求。

• url - 发送通知的 URL
• secret - 用于签名 webhook 有效负载的同步密钥

有关详细信息，请参阅 通知。

email

对于某些事件将发送电子邮件。

• from - 发送电子邮件的电子邮件地址
• to - 接收电子邮件的电子邮件地址

仅指定 from 和 to 时，如果已配置，git-next 将尝试使用 sendmail 发送电子邮件。

或者，您可以使用 SMTP 中继。

smtp

将使用 SMTP 中继发送电子邮件。

• hostname - SMTP 中继服务器
• username - 用于认证的账户
• password - 用于认证的密码

storage

[storage]
path = "./data"

git-next 将为要监视的每个仓库创建裸克隆。它们将全部创建在此目录中。这些数据不需要备份，因为当服务器启动时，任何缺失的信息都将克隆。

• path - 存储监视仓库本地副本的目录

forge

在 forge 树中，指定您要监视其仓库的每个 forge。

为您的 forge 分配一个别名，例如 default、gh、github。

例如：

[forge.github]
forge_type = "GitHub"
hostname = "github.com"
user = "username"
token = "api-key"

• forge_type - 其中之一：ForgeJo 或 GitHub
• hostname - forge 的主机名
• user - 用于认证的用户
• token - 用户的应用程序令牌。有关每个 forge 所需权限的详细信息，请参阅下文。

通常情况下，用户需要能够向 main 推送，并能够向 next 强制推送。

仓库

对于每个 forge，您需要指定要监控的 forge 上的哪些仓库。它们不需要是 user 拥有的，但 user 必须拥有上述每个仓库的 push 和 force-push 权限。

例如：

[forge.github.repos]
my-repo = { repo = "owner/repo", branch = "main", gitdir = "/home/pcampbell/project/my-repo" }

[forge.github.repos.other-repo]
repo = "user/other"
branch = "master"
main = "master"
next = "ci-testing"
dev = "trunk"

请注意，toml 允许在一行或多行中指定值。两者是等效的。在 my-repo 和 other-repo 之间不等效的是，其中一个将需要在仓库内部配置一个配置文件。 other-repo 指定了要使用的 main、next 和 dev 分支，而 my-repo 则没有。

一个示例 .git-next-toml 文件，该文件需要存在于 my-repo 的 owner/repo 仓库中，位于 main 分支上

[branches]
main = "main"
next = "next"
dev = "dev"

• repo - 要监控的仓库的所有者和名称
• branch - 如果需要，查找 .git-next.toml 文件的分支
• gitdir - (可选) 您可以使用该目录中的仓库本地副本
• main - 要用作 main 的分支
• next - 要用作 next 的分支
• dev - 要用作 dev 的分支

gitdir

关于使用 gitdir 的附加说明

当指定 gitdir 值时，在该目录克隆的仓库将被用于执行相当于 git fetch、git push 和 git push --force-with-lease 的操作。

这些命令不会影响您的工作树内容，也不会更改任何本地分支。只会更新远程 forge 上分支的详细信息。

目前，如果 forge 和仓库与作为 origin 远程指定的 forge 和仓库相同，则 git-next 可以使用 gitdir。否则，行为未经验证且未定义。

Webhook 通知

向用户发送 Webhook 通知时，它们将使用标准 Webhooks 格式发送。这意味着所有 POST 消息都具有以下头信息

• Webhook-Id
• Webhook-Signature
• Webhook-Timestamp

Events

Dev Not Based on Main

此消息 type 表示 dev 分支不是基于 main 的。

需要采取的操作：将 dev 分支变基到 main 分支。

示例有效负载

{
  "data": {
    "branches": {
      "dev": "dev",
      "main": "main"
    },
    "forge_alias": "jo",
    "repo_alias": "kxio",
    "log": [
      "* 9bfce91 (origin/dev) fix: add log graph to notifications",
      "| * c37bd2c (origin/next, origin/main) feat: add log graph to notifications",
      "|/",
      "* 8c19680 refactor: macros use a more common syntax"
    ]
  },
  "timestamp": "1721760933",
  "type": "branch.dev.not-on-main"
}

CI 检查失败

此消息 type 表示位于 next 分支顶部的提交未通过配置的 CI 检查。

需要采取的操作：更新提交以纠正 CI 报告的问题，或者如果问题是暂时的（例如，网络问题），则重新运行/重启您的 CI 作业。

示例有效负载

{
  "data": {
    "commit": {
      "sha": "c37bd2caf6825f9770d725a681e5cfc09d7fd4f2",
      "message": "feat: add log graph to notifications (1 of 2)"
    },
    "forge_alias": "jo",
    "repo_alias": "kxio",
    "log": [
      "* 9bfce91 (origin/dev) feat: add log graph to notifications (2 of 2)",
      "* c37bd2c (origin/next) feat: add log graph to notifications (1 of 2)",
      "* 8c19680 (origin/main) refactor: macros use a more common syntax"
    ]
  },
  "timestamp": "1721760933",
  "type": "cicheck.failed"
}

仓库配置加载失败

此消息 type 表示 git-next 无法从仓库中的 git-next.toml 文件加载仓库的配置。

需要采取行动：审查提供的 原因。

示例有效负载

{
  "data": {
    "reason": "File not found: .git-next.toml",
    "forge_alias": "jo",
    "repo_alias": "kxio"
  },
  "timestamp": "1721760933",
  "type": "config.load.failed"
}

Webhook 注册失败

此消息 类型 表示 git-next 无法将其 webhook 注册到 forge 仓库，因此当仓库中的分支更新时，将不会收到更新。

需要采取行动：审查提供的 原因。

示例有效负载

{
  "data": {
    "reason": "repo config not loaded",
    "forge_alias": "jo",
    "repo_alias": "kxio"
  },
  "timestamp": "1721760933",
  "type": "webhook.registration.failed"
}

行为

分支名称是可以配置的，但我们将讨论 main、next 和 dev。

开发在 dev 分支上进行，其中每个提交都应能够通过 CI 检查。

（注意：在图中，mermaid 无法在同一提交中显示 main 和 next，因此我们将 next 显示为空）

gitGraph
    commit
    commit

    branch next

    branch dev
    commit
    commit
    commit

当 git-next 服务器看到 dev 分支领先于 next 分支时，它将把 next 分支快速前进一个提交到 dev 分支。

gitGraph
    commit
    commit

    branch next
    commit

    branch dev
    commit
    commit

然后，它将等待 CI 检查通过新更新的 next 分支。当 next 分支的 CI 检查通过时，它将把 main 分支快速前进到 next 分支。我们返回到顶部并重新开始。

gitGraph
    commit
    commit
    commit

    branch next

    branch dev
    commit
    commit

如果 next 分支的 CI 检查失败，开发者应在他们的 dev 分支的历史中 更正 那个提交。然后，他们应强制推送他们的变基 dev 分支。

gitGraph
    commit
    commit

    branch next
    commit

    checkout main

    branch dev
    commit

    commit
    commit

git-next 然后将检测到 next 分支不再是 dev 分支血统的一部分，并将 next 重置回 main。然后我们返回到顶部，在 git-next 看到此处 dev 领先于 next。

当 dev 分支与 main 分支处于同一提交时，则没有挂起的提交，并且 git-next 将等待收到一个表示已推送到一个分支的 webhook。在这一点上，它将再次从顶部开始。

重要

dev 分支 应该 将 next 分支作为祖先。

然而，当 next 分支顶部的提交失败 CI 并被更正时，情况并非如此。当发生这种情况时，git-next 将 强制推送 next 分支回到与 main 分支相同的提交。

这是在 git-next 中唯一发生强制推送的情况。

简而言之，next 分支 属于 git-next。不要尝试自己更新它。 git-next 将根据其认为合适的方式更新它。

入门

要为基于主干的开发使用 git-next，请按照以下步骤操作

初始化仓库（可选）

您需要指定您正在使用的分支。您可以在仓库中或服务器配置中这样做。

要为仓库创建默认配置文件，请在您的仓库根目录中运行此命令

git next init

这将创建一个 .git-next.toml 文件。 默认

默认情况下，期望的分支是 main、next 和 dev。这三个分支中的每一个 必须 存在于您的仓库中。

初始化服务器

服务器使用文件 git-next-server.toml 进行配置。执行时，它期望在当前目录中找到此文件。

要创建默认配置文件，请运行以下命令：

git next server init

这将创建一个 git-next-server.toml 文件。 默认配置

根据您的需求编辑此文件。请参阅上面的配置部分。

运行服务器

在包含您的 git-next-server.toml 文件的目录中，运行以下命令：

git next server start

Forge

以下 Forge 受支持：

• ForgeJo（可能与 Gitea 兼容，但未经过测试）
• GitHub

注意：ForgeJo 是 Gitea 的一个硬分支，但它们目前基本上是兼容的。目前，使用 Gitea 实例的 forge_type 为 ForgeJo 应该可以正常工作。我们进行的唯一 API 调用是关于注册和注销 webhook。因此，只要这些 API 保持不变，它们应该就是兼容的。

ForgeJo

在 git-next-server.toml 中配置 Forge 如下：

[forge.jo]
forge_type = "ForgeJo"
hostname = "git.myforgejo.com"
user = "bob"
token = "..."

[forge.jo.repos]
hello = { repo = "user/hello", branch = "main", gitdir = "/opt/git/projects/user/hello.git" }             # maps to https://git.example.net/user/hello on the branch 'main'
world = { repo = "user/world", branch = "master", main = "master", next = "upcoming", "dev" = "develop" } # maps to the 'master' branch

令牌是在您的 ForgeJo 实例上创建的（例如，在 https://git.myforgejo.com/user/settings/applications），需要 write:repository 权限。

GitHub

在 git-next-server.toml 中配置 Forge 如下：

[forge.gh]
forge_type = "GitHub"
hostname = "github.com" # required even for GitHub
user = "bob"
token = "..."

[forge.gh.repos]
hello = { repo = "user/hello", branch = "main", gitdir = "/opt/git/projects/user/hello.git" }             # maps to https://github.com/user/hello on the branch 'main'
world = { repo = "user/world", branch = "master", main = "master", next = "upcoming", "dev" = "develop" } # maps to the 'master' branch

令牌在这里创建 此处，需要 repo 和 admin:repo_hook 权限。

贡献

欢迎对 git-next 做出贡献！如果您发现了一个错误或有一个功能请求，请 创建一个问题。如果您想贡献代码，请随时提交更改。

在您开始提交之前，运行 just install-hooks 命令以设置 Git Hooks。（获取 Just）

依赖关系

以下图表显示了组成 git-next 的 crate 之间的依赖关系

stateDiagram-v2

    cli --> core
    cli --> forge_forgejo
    cli --> forge_github

    forge_forgejo --> core

    forge_github --> core

许可证

git-next 在 MIT 许可证 下发布。