259 lines
6 KiB
Markdown
259 lines
6 KiB
Markdown
# 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:
|
|
|
|
```shell
|
|
cargo install git-next
|
|
```
|
|
|
|
## Configuration
|
|
|
|
- The repo has a `.git-next.toml` file in it's root. (N.B. see
|
|
[#28](https://git.kemitix.net/kemitix/git-next/issues/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)
|
|
|
|
```mermaid
|
|
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.
|
|
|
|
```mermaid
|
|
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.
|
|
|
|
```mermaid
|
|
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.
|
|
|
|
```mermaid
|
|
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:
|
|
|
|
```shell
|
|
git next init
|
|
```
|
|
|
|
This will create a `.git-next.toml` file. [Default](./default.toml)
|
|
|
|
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:
|
|
|
|
```shell
|
|
git next server init
|
|
```
|
|
|
|
This will create a `git-next-server.toml` file. [Default](./server-default.toml)
|
|
|
|
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:
|
|
|
|
```shell
|
|
git next server start
|
|
```
|
|
|
|
### Forges
|
|
|
|
The following forges are supported: [ForgeJo](https://forgejo.org) and [GitHub](https://github.com/).
|
|
|
|
#### ForgeJo
|
|
|
|
Configure the forge in `git-next-server.toml` like:
|
|
|
|
```toml
|
|
[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:
|
|
|
|
```toml
|
|
[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](https://github.com/settings/tokens/new) 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](https://git.kemitix.net/kemitix/git-next/issues/new).
|
|
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](https://just.systems/man/en/chapter_3.html))
|
|
|
|
## Crate Dependency
|
|
|
|
The following diagram shows the dependency between the crates that make up `git-next`:
|
|
|
|
```mermaid
|
|
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](./LICENSE).
|