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](../technicals/root_repository.md) to discover repositories or to add a new one: `git clone ssh://yourDomainName.yourTLD/ && cd yourDomainName.yourTLD`.
20
21### Create your first repository
22
23In the [root repository](../technicals/root_repository.md) open `.gitroot/repositories.yml` and add:
24
25```diff
26  root:
27    kind: normal
28    defaultbranch: main
29+ repo1:
30+  defaultbranch: main
31```
32
33Like you are not the owner of the instance, you need to create a branch: `git checkout -b addMyRepo1`.
34
35Commit and push: `git add . && git commit -m "add repo1 repository" && git push`.
36
37By default GitRoot use `main` has [defaultBranch](../technicals/default_branch.md) but you can put every name you like.
38
39If 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.
40
41When 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`
42
43> To delete a repository see [delete repository](../how-tos/delete_repository.md)
44
45### Use a plugin
46
47GitRoot 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.
48
49If 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.
50
51```diff
52   url: "file:///plugins/ladybug/ladybug-0.0.1.wasm"
53   name: ladybug
54-  active: false
55+  active: true
56  run:
57  - path: issues/**/*.md
58```
59
60For more details on plugins rights [read the documentation](../how-tos/plugin_rights.md).
61
62## Use a repository
63
64You 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.
65
66### Clone and init
67
68Enter `git clone ssh://yourDomainName.yourTLD/repo1 && cd repo1`.
69
70After 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.
71
72### Graft
73
74If your instance use the [grafter plugin](../../plugins/name/grafter.md), 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.