GitRoot

 1<!--
 2SPDX-FileCopyrightText: 2025 Romain Maneschi <romain@gitroot.dev>
 3
 4SPDX-License-Identifier: CC-BY-SA-4.0
 5-->
 6
 7# GitRoot usage when you are a guest
 8
 9You have found a working instance of GitRoot, but you don't know how to create a repository or participate in an existing repository, this tutorial is for you.
10
11In this tutorial we use `yourDomainName.yourTLD` as instance. Meaning that http connexion is served under `80` port and `22` for ssh.
12
13This tutorial has 2 parts [create a repository](#create-a-repository) and [use a repository]()
14
15## Create a repository
16
17### Clone root repository
18
19In GitRoot all is stored in git. Even the repositories hosted on the instance. You need to clone the `root` repository to discover repositories or to add a new one: `git clone ssh://yourDomainName.yourTLD/ && cd yourDomainName.yourTLD`.
20
21As always in GitRoot you need to Configure your local git client by running `.gitroot/init.sh`.
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
37Like you are not the owner of the instance, you need to create a branch: `git checkout -b addMyRepo1`.
38
39Commit and push: `git add . && git commit -m "add repo1 repository" && git push`.
40
41By default GitRoot use `main` has [defaultBranch](../technicals/default_branch.md) but you can put every name you like.
42
43If your instance use the grafter plugin, you'll need to pull changes `git pull origin addMyRepo1`, and if a file named `grafts/addMyRepo1.md` appear, you need to review it and follow their instructions.
44
45When the instance owner merge your branch in the default one you will be able to clone and use your new repository, don't forget to init your local git config: `git clone ssh://yourDomainName.yourTLD/repo1 && cd repo1 && .gitroot/init.sh`
46
47> To delete a repository see [delete repository](../how-tos/delete_repository.md)
48
49### Use a plugin
50
51GitRoot has configured your repository with all plugins available on the instance. But GitRoot has not activated them, it's up to you to use them or not.
52
53If you wnat to active them you can turn `active: false` to `active: true` in the `.gitroot/plugins.yml`. Don't forget to look/edit default configuration.
54
55```diff
56   url: "file:///plugins/ladybug/ladybug-0.0.1.wasm"
57   crc32: null
58   name: ladybug
59-  active: false
60+  active: true
61  run:
62  - path: issues/**/*.md
63```
64
65For more details on plugins rights [read the documentation](../how-tos/plugin_rights.md).
66
67## Use a repository
68
69You have find a good repository where you want to contrinute? In GitRoot it's super easy, no need to register, no need to anything except your old git friend.
70
71### Clone and init
72
73Enter `git clone ssh://yourDomainName.yourTLD/repo1 && cd repo1 && .gitroot/init.sh`.
74
75> Don't want to run unknown sh? See [manually init client](../how-tos/manual_init_client.md).
76
77After that, you can make a branch `git checkout -b myBranch` and start contributing. When you are happy with the changes, commit and push them `git add . && git commit -m "my changes" && git push`, GitRoot will handle all the rest.
78
79### Graft
80
81If your instance use the grafter plugin, you'll need to pull changes `git pull`, and if a file named `grafts/myBranch.md` appear, you need to review it and follow their instructions. A graft in GitRoot is like a (merge/pull)-request in other forges. But as always with GitRoot all is managed through git.