git-next

git-next is a combined server and command-line tool that enables trunk-based development workflows where each commit must pass CI before being included in the main branch.

Features

• Enforce the requirement for each commit to pass the CI pipeline before being included in the main branch
• Provide a server component that manages the trunk-based development process
• Ensure a consistent, high-quality codebase by preventing untested changes from being merged

Prerequisits

• Rust 1.76.0 or later
• pgk-config
• libssl-dev
• clang-16
• mold

Installation

You can install git-next using Cargo:

cargo install --path .

Configuration

• The repo has a .git-next.toml file in it's root. (N.B. see #28 for a planned alternative)
• CI checks should be configured to run when the next branch is pushed.
• The dev branch must have the main branch as an ancestor.
• The next branch must have the main branch as an ancestor.

Behaviour

Development happens on the dev branch, where each commit is expected to be able to pass the CI checks.

(Note: in the diagrams, mermaid isn't capable of showing main and next on the same commit, so we show next as empty)

gitGraph
    commit
    commit

    branch next

    branch dev
    commit
    commit
    commit

When the git-next server sees that the dev branch is ahead of the next branch, it will push the next branch fast-forward one commit along the dev branch.

gitGraph
    commit
    commit

    branch next
    commit

    branch dev
    commit
    commit

It will then wait for the CI checks to pass for the newly updated next branch. When the CI checks for the next branch pass, it will push the main branch fast-forward to the next branch.

gitGraph
    commit
    commit
    commit

    branch next

    branch dev
    commit
    commit

If the CI checks should fail for the next branch, the developer should amend that commit in the history of their dev branch. They should then force-push their rebased dev branch.

gitGraph
    commit
    commit

    branch next
    commit

    checkout main

    branch dev
    commit

    commit
    commit

git-next will then detect that the next branch is no longer part of the dev branch ancestory, and reset next back to main. We then return to the top, where git-next sees that dev is ahead of next.

Important

The dev branch should have the next branch as an ancestor.

If the git-next server finds that this isn't the case, it will force-push the next branch back to the same commit as the main branch.

In short, the next branch belongs to git-next.

Getting Started

To use git-next for trunk-based development, follow these steps:

Initialise the repo

You need to specify which branches you are using

To create the default config file, run this command in the root of your repo:

git next init

This will create a .git-next.toml file. Default

By default the expected branches are main, next and dev. Each of these three branches must exist in your repo.

Initialise the server

The server uses the file git-next-server.toml for configuration.

The create the default config file, run this command:

git next server init

This will create a git-next-server.toml file. Default

Edit this file to your needs.

Specify the access token.

The branch parameter for the repo identies the branch where the .git-next.toml file should be found.

Run the server

In the directory with your git-next-server.toml file, run the command:

git next server start

Forges

The following forges are supported: ForgeJo and GitHub.

ForgeJo

Configure the forge in git-next-server.toml like:

[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

The token is created /user/settings/applications and requires the write:repository permission.

GitHub

Configure the forge in git-next-server.toml like:

[forge.gh]
forge_type = "GitHub"
hostname = "github.com"
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

The token is created here and requires the repo and admin:repo_hook permissions.

Contributing

Contributions to git-next are welcome! If you find a bug or have a feature request, please create an issue. If you'd like to contribute code, feel free to submit a merge request.

Before you start committing, run the just install-hooks command to setup the Git Hooks. (Get Just)

Crate Dependency

The following diagram shows the dependency between the crates that make up git-next:

stateDiagram-v2
    cli --> server
    cli --> git

    server --> config
    server --> git
    server --> forge
    server --> repo_actor

    git --> config

    forge --> config
    forge --> git
    forge --> forgejo
    forge --> github

    forgejo --> config
    forgejo --> git

    github --> config
    github --> git

    repo_actor --> config
    repo_actor --> git
    repo_actor --> forge

License

git-next is released under the MIT License.