GitRoot

  1<!--
  2SPDX-FileCopyrightText: 2025 Romain Maneschi <romain@gitroot.dev>
  3
  4SPDX-License-Identifier: EUPL-1.2
  5-->
  6
  7# GitRoot
  8
  9GitRoot is a tiny yet powerfull git forge. Download one binary, launch it and you have a forge. Install plugins and only your imagination is the limit.
 10
 11## Getting Started
 12
 13These instructions will give you a copy of the project up and running on your local machine for development and testing purposes. See [gitroot.dev](https://gitroot.dev) to understand the project itself and the [documentation](./doc/index.md) to discover how to use it.
 14
 15### Prerequisites
 16
 17All this tools need to be available in your path:
 18
 19- [git](https://git-scm.com/): the git client to be able to pull and push code
 20- [bash](https://www.gnu.org/software/bash/manual/bash.html): a lot of scripts are written to be executed in bash
 21
 22Then you have two choices:
 23
 24- [mise](https://mise.jdx.dev/): a dev env manager in which a simple `mise install` will set all requierements
 25
 26Or install manually (look into [mise.toml](https://gitroot.dev/gitroot/worktree/mise.toml) for forgotten tools):
 27
 28- [make](https://www.gnu.org/software/make/): to simplify the call to the scripts we have a makefile in the root directory and some others in sub-directories
 29- [golang](https://go.dev/): GitRoot is written in go [see rationals](./doc/rationales/rationale_golang.md) if you want to know why
 30- [tinygo](https://tinygo.org/): first plugins are written in golang and compiled thanks to tinygo, in the future a lot of others languages will comes
 31- [nodejs/npm](https://nodejs.org): to compile plugin in [assemblyscript](https://www.assemblyscript.org/)
 32- [rust](https://rust-lang.org): to compile plugin in rust
 33
 34### Installing
 35
 36Clone the code `git clone ssh://gitroot.dev/` and init your git client for this repository `.gitroot/init.sh`.
 37
 38> Don't want to run unknown sh? See [manually init client](./doc/how-tos/manual_init_client.md).
 39
 40Don't forget to make a branch before coding `git checkout -b myWork`. As GitRoot allow anybody to push a branch (if no one as already do == a branch name need to be unique) you don't need to register or to fork something. Branch, code, commit and push, is what you need to do.
 41
 42> More on the [users and branches workflow](./doc/technicals/users_file.md) in GitRoot.
 43
 44## Build
 45
 46To build GitRoot use `make build` and it will generate a `gitroot` binary in the root of the project.
 47
 48Launch it with `./gitroot -data="./data"`, your forge is accessible on `git clone ssh://127.0.0.1:4545/` or by opening `http://127.0.0.1:4546/`.
 49
 50For more details on usage, please read the [doc](./doc/index.md).
 51
 52## Running the tests
 53
 54GitRoot has differents kind of tests:
 55
 56- unit tests in go files, execute them with `make test`
 57- integration tests in sh files, they will create data directory in `/tmp`, execute them with `make testsuite`
 58
 59To run all in one command: `make testall`
 60
 61## Deployment
 62
 63See the [documentation](./doc/tutorials/deploy_instance.md) to deploy an instance.
 64
 65## Contributing
 66
 67Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code
 68of conduct, and the process for submitting code to us.
 69
 70## Versioning
 71
 72We use [Semantic Versioning](http://semver.org/) for versioning. For the versions available, see the [changelog](./CHANGELOG.md).
 73
 74## Authors
 75
 76As in any GitRoot repository, find contributors in [.gitroot/users.yml](./.gitroot/users.yml).
 77
 78## Release
 79
 80To release a version of GitRoot:
 81
 82- make the directory for issues `mkdir issues/close/v0.1.0`
 83- move all issues from `issues/close` to `issues/close/v0.1.0` with `find issues/close/. -maxdepth 1 \( ! -type d \) -exec sh -c 'mv  "$@" issues/close/v0.1.0' _ {} \;`
 84- update [changelog](./CHANGELOG.md) with date, version, next and last
 85- commit `git add . && git commit -m ":bookmark: v0.1.0"`
 86- create a tag: `git tag -a v0.1.0 -m "Version 0.1.0"`
 87- build the binary: `make build`
 88- get binary infos: `./releases/0.1.0/gitroot-0.1.0-darwin-amd64 --version`
 89- update [changelog](./CHANGELOG.md) with commit info and add next section
 90- commit `git add . && git commit -m ":sparkles: start next"`
 91- release binary: `scp gitroot-0.1.0 gitroot.dev` and update last `ssh gitroot.dev "rm -f gitroot-last && cp gitroot-0.1.0 gitroot-last"`
 92- git push (don't push tag we don't care about that, only commit is important)
 93
 94## License
 95
 96This project is licensed under multiple licences. GitRoot follow [spdx](https://spdx.dev/) convention, so you can find all licences in `licences` directory. Each file contain it's own licence, but here is a brief summary as of May 2025:
 97
 98- app/server: EUPL-1.2
 99- app/libs: MIT
100- app/plugin: EUPL-1.2
101- doc: CC-BY-SA-4.0
102
103So you can develop a plugin in any licence you want. To encourage that, libs to help you build a plugin are MIT. All the code EUPL will stay EUPL and any modification should be republied. See more on [rationals about EUPL](./doc/rationales/rationale_licence.md).
104
105For more accurate information, check the [REUSE.toml](./REUSE.toml) and/or individual files.