GitRoot

 1<!--
 2SPDX-FileCopyrightText: 2025 Romain Maneschi <romain@gitroot.dev>
 3
 4SPDX-License-Identifier: CC-BY-SA-4.0
 5-->
 6
 7# Plugin rights
 8
 9Plugins are the true power of GitRoot. But, as you know, with power comes responsability. To be sure to understand what a plugin can and can't, GitRoot expose all details in `.gitroot/plugins.yml`.
10
11## First example
12
13Taking ladybug as an example:
14
15```yml
16- url: plugins/ladybug/ladybug-0.0.1.wasm
17  name: ladybug
18  active: true
19  run:
20    - path: issues/**/*.md
21      branch:
22        - "*"
23      when:
24        - add
25        - mod
26      write:
27        git:
28          - path: issues/**/*.md
29            can:
30              - mod
31        web: []
32      configuration: ...
33```
34
35You can read: "for all branches in your repository, when you modify or create any markdown file in the directory or a sud-directory of issues execute the plugin. During execution it can write in any markdown file in the directory or a sud-directory of issues in modification."
36
37But it can't create a file in git or write in web.
38
39Be carrefull, the plugin will be called for modification of `issues/1.md`, but it can modify `issues/2.md` if it need to do.
40
41_Configuration has been omitted because it depend on each plugin._
42
43## More complexe example
44
45If you look at the plugins.yml of GitRoot itself you will see that apex plugin have a more complexe configuration:
46
47```yml
48- url: plugins/apex/apex-0.0.1.wasm
49  name: apex
50  active: true
51  run:
52    - path: "**/*"
53      branch:
54        - main
55      when:
56        - add
57        - mod
58        - del
59      write:
60        git:
61          - path: index.md
62            can:
63              - add
64        web:
65          - path: "**/*"
66            can:
67              - add
68              - mod
69              - del
70              - append
71      configuration: &apexConf
72        header: ...
73    - path: "grafts/*"
74      branch:
75        - "*"
76        - "!main"
77      when:
78        - add
79        - mod
80        - del
81      write:
82        git: []
83        web:
84          - path: "grafts/*"
85            can:
86              - add
87              - append
88      configuration:
89        <<: *apexConf
90        generateGitWorktree: false
91```
92
93You can read it as: "On the main branch, every file can be rendered in the web. An index.md can be created in the git worktree. But for all other branches, only files in the graft directory can be rendered in the web and only to create or append modifications."
94
95Why? Because in GitRoot everybody can create a branch. Imagine if a bad person come, create a branch and delete all the content of the repository. Then push it, if apex render that in the web, your repository website will be empty... What we want is: render it when the change are commited to the default branche.
96
97But we also want to see all other grafts. So we tell to the plugin system to only accept new graft. If user make a bad thing nothing will it the web content.