GitRoot

GitRoot is a small yet powerful git forge. Download one binary, launch it and you have a forge that can: create git repositories, manage who can access to what repositories. Nothing more, nothing less. GitRoot 是一个精简而强大的 Git 代码托管平台（Git forge）。只需下载一个二进制文件并运行，你就能拥有一个可以创建 Git 仓库并管理仓库访问权限的托管平台。不多不少，恰到好处。

Install plugins and you will be able to: create issues, roadmap, sprint, milestone… represent them in boards, review/merge branches (called grafts in gitroot), represent them all and many more in a web interface. All of these plugins are completely independent. Yes, you can have boards without the web interface. How? See raw GitRoot issues board, try it for yourself and you will love it. Wants more? Build your own plugin! 安装插件后，你还可以实现：创建 Issue、路线图（roadmap）、冲刺（sprint）、里程碑（milestone）……在看板中展示它们，审查/合并分支（在 GitRoot 中称为 grafts），并通过 Web 界面展示所有这些内容等等。所有插件都是完全独立的。没错，你甚至可以在没有 Web 界面时使用看板。怎么做到的？看看 GitRoot 的原始 Issue 看板，亲自试一试，你一定会爱上它。想要更多功能？那就构建你自己的插件吧！

Why am I doing this? I’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. Every project is unique, so why don’t we have the freedom to modify our forge to suit our own project? 我为什么要开发这个项目？我开发 GitRoot 是因为我找不到任何工具能满足我对自己项目的需求。同时，你可能也想为自己的项目实现一些不同的功能，一些与我心目中“完美项目”不同的东西。每个项目都是独特的，所以为什么我们不能拥有根据自身需求修改托管平台的自由呢？

So I try to follow these rules when developing my forge: 因此，我在开发这个平台时尝试遵循以下原则：

As a developer I want: 作为开发者，我想要：

• a repository containing all my data: code, issues, (pull|merge)-request, boards
• 一个包含我所有数据的仓库：代码、Issue、(Pull|Merge) Request、看板
• all I need to promote my project: landing page, translation, ticketing, forum
• 推广项目所需的一切：落地页、翻译、工单系统、论坛
• the ability to migrate my project into a new server forge: no script migration, no loose data, no loose attribution
• 将项目迁移到新服务器的能力：无需脚本迁移，不丢失数据，不丢失贡献归属

As a developer I want to have a forge crafted for my unique project. 作为开发者，我想要一个为我独特项目量身定制的托管平台。

As a developer I don’t want: 作为开发者，我不想要：

• to open my browser to manage my data: (pull|merge)-request, issues
• 打开浏览器来管理我的数据：(Pull|Merge) Request、Issue
• the first representation of my project is a list of files and directories
• 项目的第一展示形式仅仅是文件和目录列表
• my forge chooses my workflow
• 由托管平台来决定我的工作流
• issues: what is a sprint vs a milestone vs an epic vs an user-story?
• 关于 Issue 的定义：什么是冲刺、里程碑、史诗（Epic）或用户故事（User-story）？
• to have 100 menus to configure who can do what
• 为了配置权限而面对上百个菜单

As a developer I don’t want a complex forge to manage my project. 作为开发者，我不想要一个复杂的托管平台来管理我的项目。

As an administrator I want: 作为管理员，我想要：

• an easy to deploy forge: no dependency, no database
• 一个易于部署的平台：无依赖、无数据库
• to configure what my users can do
• 配置用户权限的能力
• my users can request what they want: no need to send email/chat to create or access to a project or a feature
• 用户可以自主申请权限：无需通过邮件或聊天工具来创建项目或获取功能访问权

As an administrator I want a forge that is easy to install and to maintain. 作为管理员，我想要一个易于安装和维护的托管平台。

As an administrator I don’t want: 作为管理员，我不想要：

• headaches to upgrade my forge
• 升级平台时的头疼问题
• to give my data (or user data) to someone else
• 将我的数据（或用户数据）交给他人
• to depend on big players who can table-flip their forge at any time
• 依赖那些随时可能“掀桌子”关停服务的大厂

As an administrator I don’t want to depend on anyone else. 作为管理员，我不想要依赖任何人。

If you are like me, you will love GitRoot. It’s not ready yet, but it will be, especially if you give me a hand. 如果你和我一样，你一定会喜欢 GitRoot。它目前尚未完全成熟，但未来会变得更好，特别是如果你愿意助我一臂之力的话。

How it works? In GitRoot everything 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. 它是如何工作的？在 GitRoot 中，一切都存储在 Git 中，而不是数据库里，也不是 Git 树中隐藏的二进制大对象（blob）里。所有内容都以纯文本文件的形式存储在你的代码旁边。

How 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. Initially, you’re the only one to have access to your default branch. If someone else tries to push to this branch, GitRoot will refuse its modifications. However, 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. If 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. 你如何确保没人能修改不该修改的文件？通过分支限制。每个 GitRoot 仓库都包含一个 .gitroot/users.yml 文件。该文件向 GitRoot 指示谁可以在哪里写入。最初，只有你拥有默认分支的访问权限。如果其他人尝试推送到该分支，GitRoot 将拒绝其修改。但是，任何人都可以创建分支。当创建并推送分支时，GitRoot 会为该用户添加该分支的权限，这意味着其他人无法修改它。如果你通过编辑 .gitroot/users.yml 或合并一个用户自行添加的分支来添加用户，该用户将能够推送到默认分支。

All 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 which represent the current state of your repository. As 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 of your root repository. See more details in the documentation. GitRoot 的所有功能都围绕这一概念展开。这意味着每个人都可以读取文件并在本地或新分支中修改它们。但只有所有者才能将它们合并到代表仓库当前状态的默认分支中。由于你的托管平台是由一个根仓库（root repository）管理的，这一概念允许你在自己的平台上管理一切：当你向根仓库的默认分支添加（或合并）.gitroot/repositories.yml 的更改时，就会创建一个新仓库。更多详情请参阅文档。

When will be it available? GitRoot is currently in alpha version. Feel free to experiment with it, but don’t use it for production yet. 它何时可用？GitRoot 目前处于 Alpha 版本。欢迎随意尝试，但请暂勿用于生产环境。

GitRoot can: GitRoot 可以：

• Create/delete repositories
• 创建/删除仓库
• Accept git command through ssh
• 通过 SSH 接收 Git 命令
• Manage users (who can write where on repo/branch level)
• 管理用户（在仓库/分支级别控制写入权限）
• Install plugins
• 安装插件
• Activate plugins for a repository
• 为仓库激活插件
• Run plugins on your worktree at install
• 在安装时对工作树运行插件
• Run plugins on diff every commit after install
• 安装后在每次提交的差异（diff）上运行插件
• Visualize repository with http
• 通过 HTTP 可视化仓库

What I want to do before version 1.0: 在 1.0 版本之前，我计划实现：

• Update GitRoot and plugins
• 更新 GitRoot 和插件
• Manage users (who can write where on file level)
• 管理用户（在文件级别控制写入权限）
• Accept git command through http
• 通过 HTTP 接收 Git 命令
• Manage repositories in group and sub-group
• 管理组和子组仓库
• Stabilise the plugin API
• 稳定插件 API

Where is the project? Actually, you are currently on the project. Yes this is GitRoot! Well you are on the instance of GitRoot which hosts the code of GitRoot. Unfortunatly this instance is reserved for GitRoot itself. If you want to try GitRoot for your own project, please read the documentation. 项目在哪里？实际上，你现在就在项目里。没错，这就是 GitRoot！准确地说，你正在访问托管 GitRoot 代码的 GitRoot 实例。遗憾的是，此实例仅供 GitRoot 自身使用。如果你想为自己的项目尝试 GitRoot，请阅读文档。

How to contribute? You will find anything you need to know into the documentation. Since GitRoot is itself a GitRoot repository you should be able to contribute to it. On 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 to understand how it works. And 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. 如何贡献？你可以在文档中找到所需的一切信息。由于 GitRoot 本身就是一个 GitRoot 仓库，你应该能够为其做出贡献。在此实例中，我们使用了一些插件。例如，grafter 插件，它管理代码片段如何合并到默认分支。因此，请务必阅读贡献指南以了解其工作原理。是的，由于 GitRoot 将所有数据存储在 Git 中，在为本项目做出贡献（代码、Issue、翻译等）之前，你需要了解如何使用 Git。未来，我希望能够允许直接从浏览器执行 git commit 和 git push 命令，以便任何人都能参与进来。