craft your forge, build your project, grow your community freely
1<!--
2SPDX-FileCopyrightText: 2025 Romain Maneschi <romain@gitroot.dev>
3 4SPDX-License-Identifier: CC-BY-SA-4.0
5--> 6 7# GitRoot
8 9GitRoot is a small yet powerfull git forge. Download one binary, launch it and you have a forge that can :
10 11- create git repositories
12- manage who can access to what repositories
13 14Nothing more, nothing less.
15 16Install plugins and you will be able to:
17 18- create issues, roadmap, sprint, milestone...
19- represent them in boards
20- review/merge branches (called grafts in gitroot)
21- represent them all and many more in a web interface
22 23> All of these plugins are completely independant. Yes, you can have boards without the web interface. How ? [See raw GitRoot issues board](https://gitroot.dev/gitroot/worktree/boards/issues.md.html), try it for yourself and you will love it.
24 25**Wants more? Build your own plugin!**
26 27# Why am I doing this?
28 29I'm building GitRoot because I didn't find any tool that can let me do what I want for my project. But at the same time, you may want to make something different for your own project, something different of my idea of a perfect project.
30 31Every project is unique, so why don't we have the freedom to modify our forge to suit our own project ?
32 33So I try to follow these rules when developing my forge:
34 35## As a developer I want:
36 37- a repository containing all my data: code, issues, `(pull|merge)-request`, boards
38- all I need to promote my project: landing page, translation, ticketing, forum
39- the ability to migrate my project into a new server forge: no script migration, no loose data, no loose attribution
40 41> As a developer I want to have a forge crafted for my unique project.
42 43## As a developer I don't want:
44 45- to open my browser to manage my data: `(pull|merge)-request`, issues
46- the first representation of my project is a list of files and directories
47- my forge chooses my workflow issues: what is a sprint vs a milestone vs an epic vs an user-story?
48- to have 100 menus to configure who can do what
49 50> As a developer I don't want a complexe forge to manage my project.
51 52## As an administrator I want:
53 54- an easy to deploy forge: no dependency, no database
55- to configure what my users can do
56- my users can request what they want: no need to send email/chat to create or access to a project or a feature
57 58> As an administrator I want a forge that is easy to install and to maintain.
59 60## As an administrator I don't want:
61 62- headaches to upgrade my forge
63- to give my data (or user data) to someone else
64- to depend on big players who can table-flip their forge at any time
65 66> As an administrator I don't want to depend on anyone else.
67 68### _If you are like me, you will love GitRoot._
69 70It's not ready yet, but it will be, especially if you give me a hand.
71 72# How it works?
73 74In GitRoot everyting is stored in git, not in a database, not in a hidden blob in your git tree. Everything is stored in plain files aside your code.
75 76How can you be sure no one writes on a file that they must not? **Restrict by branch.** Every GitRoot repository comes with a `.gitroot/users.yml` file. This file gives the instructions to GitRoot who can write where.
77 78Initially, you're the only one to have access to your [default branch](./docs/technicals/default_branch.md). If someone else tries to push to this branch, GitRoot will refuse its modifications.
79 80However, everyone can create a branch. When creating and pushing a branch, GitRoot will add right for this user to this branch. This means that no one else will be able to modify it.
81 82If you add a user, by editing `.gitroot/users.yml` or by merging a branch where a user has added itself, this user will be able to push to the [default branch](./docs/technicals/default_branch.md).
83 84All GitRoot features are articulated around this concept. This means that everyone can read files and modify them, locally or into a new branch. But only the owner can merge them in the [default branch](./docs/technicals/default_branch.md) which represent the current state of your repository.
85 86As your forge is managed by a root repository, this concept permit to manage everything on your own forge: a repository is created when you add (or merge) a change of `.gitroot/repositories.yml` in your [default branch](./docs/technicals/default_branch.md) of your root repository.
87 88See more details in the [documentation](./docs/).
89 90# When will be it available?
91 92GitRoot is currently in **alpha** version. Feel free to experiment with it, but **don't use it for production yet**.
93 94GitRoot can:
95 96- Create/delete repositories
97- Accept git command through ssh
98- Manage users (who can write where on repo/branch level)
99- Install plugins
100- Activate plugins for a repository
101- Run plugins on your worktree at install
102- Run plugins on diff every commit after install
103- Visualize repository with http
104105What I want to do before version 1.0:
106107- Update GitRoot and plugins
108- Manage users (who can wright where on file level)
109- Accept git command through http
110- Manage repositories in group and sub-group
111- Stabilise the plugin API
112113# Where is the project?
114115Actually, you are currently on the project. Yes this is GitRoot!
116117Well you are on the instance of GitRoot which hosts the code of GitRoot. Unfortunatly this instance is reserved for GitRoot itself.
118119If you want to try GitRoot for your own project, please read [the documentation](./doc/index.md).
120121# How to contribute?
122123You will find anything you need to know into [the documentation](./doc/index.md). Since GitRoot is itself a GitRoot repository you should be able to contribute to it.
124125On this instance we use some plugins. For example, the `grafter` plugin which manages how a portion of code can be incorporated into the default branch. So be sure to read [the contributing](./CONTRIBUTING.md) to understand how it works.
126127And yes, as GitRoot stores all data in git, you need to know how to use git before contributing to this project (code, issue, translation...). In the future I hope to be able to allow to do `git commit` and `git push` commands directly from the browser, so that anybody will be able to participate.