GitRoot

  1<!--
  2SPDX-FileCopyrightText: 2025 Romain Maneschi <romain@gitroot.dev>
  3
  4SPDX-License-Identifier: CC-BY-SA-4.0
  5-->
  6
  7# From zero to hero
  8
  9You are intriged by GitRoot, but want to try it before deploye one instance? In this tutorial I propose to you to launch a local instance on your post. Linux users you are welcome, Mac one should work but never tested, **Windows user sorry but this will not work**.
 10
 11## Download and run
 12
 13Dowload: `wget -O gitroot https://gitroot.dev/releases/0.2.0/gitroot-0.2.0-linux-amd64 && chmod +x gitroot` (binaries for others arch/cpu can be found in [versions page](../../CHANGELOG.md)).
 14
 15Initialisation: `./gitroot --initConfig ./conf.yml`. You can review the file `conf.yml`, but for now default configuration should be good.
 16
 17Run: `./gitroot -config="./conf.yml" -data="./data"`.
 18
 19GitRoot will create a directory `data` where you launch it. All its data will be stocked here. By default GitRoot listen to port `4545` for ssh and `4546` for http.
 20
 21## Clone root repository
 22
 23In GitRoot all is stored in git. Even the repositories hosted on your instance. You need to clone the `root` repository to discover repositories or to add a new one: `git clone ssh://$PSEUDO@127.0.0.1:4545/ -o root && cd root`.
 24
 25Configure your local git client by running `.gitroot/init.sh`, then all is ok you can start adding code, repository or user.
 26
 27> Don't want to run unknown sh? See [manually init client](../how-tos/manual_init_client.md).
 28
 29## Create your first repository
 30
 31In the `root` repository open `.gitroot/repositories.yml` and add:
 32
 33```diff
 34  root:
 35    kind: normal
 36    defaultbranch: main
 37+ repo1:
 38+  defaultbranch: main
 39```
 40
 41Commit and push, GitRoot will build your new repo: `git add . && git commit -m "add repo1 repository" && git push`.
 42
 43By default GitRoot use `main` has [defaultBranch](../technicals/default_branch.md) but you can put every name you like.
 44
 45You can clone and use your new repository, don't forget to init your local git config: `git clone ssh://127.0.0.1:4545/repo1 && cd repo1 && .gitroot/init.sh`
 46
 47> To delete a repository see [delete repository](../how-tos/delete_repository.md)
 48
 49## Install plugin
 50
 51GitRoot by itself don't do so much, but when you add some plugins it start to be a full forge.
 52
 53Before using a plugin in your repo, instance forge need to install it.
 54
 55In your root repository edit `.gitroot/plugins.yml` and add your first plugin:
 56
 57```yml
 58- url: "https://gitroot.dev/releases/0.2.0/ladybug-0.0.2.wasm"
 59  checksum: "sha256:0c755bb2dc5cc037216b29ba1709875afee425ee429b6be97f0d5e137067acff"
 60- url: "https://gitroot.dev/releases/0.2.0/silo-0.0.2.wasm"
 61  checksum: "sha256:66fe44b4e0984154bda0867a9b35ea39b0be3d92a89e4e542b70472fadf2f78e"
 62- url: "https://gitroot.dev/releases/0.2.0/grafter-0.0.2.wasm"
 63  checksum: "sha256:9ce5e36af1fd53a6547ec51d55356a661a05ae617b16ef97b1eae0dd0cce22c0"
 64- url: "https://gitroot.dev/releases/0.2.0/apex-0.0.2.wasm"
 65  checksum: "sha256:4c7d1b84f768a6aea11393ea2bc116a7be30fd12380fd7e11f283d5970028119"
 66```
 67
 68Git commit and push: `git add . && git commit -m "add lot of plugins" && git push`
 69
 70GitRoot add all default configuration requiered for this plugin but not active it.
 71
 72After a `git pull` you will see that GitRoot had added a commit in your root repository and in all repositories of your forge.
 73
 74```diff
 75   url: "https://gitroot.dev/releases/0.2.0/ladybug-0.0.2.wasm"
 76   checksum: "sha256:0c755bb2dc5cc037216b29ba1709875afee425ee429b6be97f0d5e137067acff"
 77+  name: ladybug
 78+  active: false
 79+  run:
 80+  - path: issues/**/*.md
 81+    branch:
 82+    - "*"
 83+    when:
 84+    - add
 85+    - mod
 86+    write:
 87+      git:
 88+      - path: issues/**/*.md
 89+        can:
 90+        - mod
 91+      web: []
 92+    configuration:
 93+      metadata:
 94+      - default: autogenerated
 95+        mandatory: true
 96+        name: id
 97+        type: crc16
 98+      - default: 50.0
 99+        mandatory: true
100+        name: priority
101+        type: int
102```
103
104> Want to delete a plugin? See [delete a plugin](../how-tos/delete_plugin.md)
105
106## Use a plugin
107
108In any repository with plugin installed you can turn `active: false` to `active: true` in the `.gitroot/plugins.yml`. Don't forget to look/edit default configuration.
109
110```diff
111   url: "file:///plugins/ladybug/ladybug-0.0.1.wasm"
112   name: ladybug
113-  active: false
114+  active: true
115  run:
116  - path: issues/**/*.md
117```
118
119For more details on plugins rights [read the documentation](../how-tos/plugin_rights.md).
120
121## Play with your forge
122
123Congratulation you have a full forge on your desktop! You can start developping something fun.
124
125You can [customize the web representation](../how-tos/customize_web.md) of your repository. Or you can use some [plugins](../index.md#plugins).
126
127But this is on your computer, you can't invite friends to play with you. For that you need to use an instance available on the web follow [deploy an instance](./deploy_instance.md) to do that.
128
129Or find a provider and [use it](./use_instance.md).
130
131But in any case enjoy your life.