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 and run GitRoot: `wget -O gitroot https://gitroot.dev/gitroot-0.1.0 && ./gitroot -data="./data"`.
 14
 15GitRoot 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.
 16
 17## Clone root repository
 18
 19In 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`.
 20
 21Configure your local git client by running `.gitroot/init.sh`, then all is ok you can start adding code, repository or user.
 22
 23> Don't want to run unknown sh? See [manually init client](../how-tos/manual_init_client.md).
 24
 25## Create your first repository
 26
 27In the `root` repository open `.gitroot/repositories.yml` and add:
 28
 29```diff
 30  root:
 31    kind: normal
 32    defaultbranch: main
 33+ repo1:
 34+  defaultbranch: main
 35```
 36
 37Commit and push, GitRoot will build your new repo: `git add . && git commit -m "add repo1 repository" && git push`.
 38
 39By default GitRoot use `main` has [defaultBranch](../technicals/default_branch.md) but you can put every name you like.
 40
 41You 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`
 42
 43> To delete a repository see [delete repository](../how-tos/delete_repository.md)
 44
 45## Install plugin
 46
 47GitRoot by itself don't do so much, but when you add some plugins it start to be a full forge.
 48
 49Before using a plugin in your repo, instance forge need to install it.
 50
 51Download some plugins:
 52
 53- `wget https://gitroot.dev/ladybug-0.0.1.wasm`
 54- `wget https://gitroot.dev/silo-0.0.1.wasm`
 55- `wget https://gitroot.dev/grafter-0.0.1.wasm`
 56- `wget https://gitroot.dev/apex-0.0.1.wasm`
 57
 58In your root repository edit `.gitroot/plugins.yml` and add your first plugin:
 59
 60```yml
 61- url: "/plugins/ladybug/ladybug-0.0.1.wasm"
 62  crc32: null
 63  name: ladybug
 64- url: "/plugins/ladybug/silo-0.0.1.wasm"
 65  crc32: null
 66  name: silo
 67- url: "/plugins/ladybug/grafter-0.0.1.wasm"
 68  crc32: null
 69  name: grafter
 70- url: "/plugins/ladybug/apex-0.0.1.wasm"
 71  crc32: null
 72  name: apex
 73```
 74
 75Git commit and push: `git add . && git commit -m "add lot of plugins" && git push`
 76
 77GitRoot add all default configuration requiered for this plugin but not active it.
 78
 79After a `git pull` you will see that GitRoot had added a commit in your root repository and in all repositories of your forge.
 80
 81```diff
 82   url: "file:///plugins/ladybug/ladybug-0.0.1.wasm"
 83   crc32: null
 84   name: ladybug
 85+  active: false
 86+  run:
 87+  - path: issues/**/*.md
 88+    branch:
 89+    - "*"
 90+    when:
 91+    - add
 92+    - mod
 93+    write:
 94+      git:
 95+      - path: issues/**/*.md
 96+        can:
 97+        - mod
 98+      web: []
 99+    configuration:
100+      metadata:
101+      - default: autogenerated
102+        mandatory: true
103+        name: id
104+        type: crc16
105+      - default: 50.0
106+        mandatory: true
107+        name: priority
108+        type: int
109```
110
111> Want to delete a plugin? See [delete a plugin](../how-tos/delete_plugin.md)
112
113## Use a plugin
114
115In 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.
116
117```diff
118   url: "file:///plugins/ladybug/ladybug-0.0.1.wasm"
119   crc32: null
120   name: ladybug
121-  active: false
122+  active: true
123  run:
124  - path: issues/**/*.md
125```
126
127For more details on plugins rights [read the documentation](../how-tos/plugin_rights.md).
128
129## Play with your forge
130
131Congratulation you have a full forge on your desktop! You can start developping something fun.
132
133You can [customize the web representation](../how-tos/customize_web.md) of your repository. Or you can use some [plugins](../index.md#plugins).
134
135But 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.
136
137Or find a provider and [use it](./use_instance.md).
138
139But in any case enjoy your life.