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](../../plugins/name/ladybug.md) as an example:
14
15```yml
16- url: https://gitroot.dev/releases/0.3.0/ladybug-0.0.3.wasm
17  checksum: sha256:adfaf88dc15ca5d53019ff194a32abec9c914c6cdf676ef4de589c1a4cfd12d4
18  name: ladybug
19  active: true
20  run:
21    - path: issues/**/*.md
22      branch:
23        - "*"
24      when:
25        - add
26        - mod
27      write:
28        git:
29          - path: issues/**/*.md
30            can:
31              - mod
32        web: []
33      configuration: ...
34```
35
36You 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."
37
38But it can't create a file in git or write in web.
39
40Be carrefull, the plugin will be called for modification of `issues/1.md`, but it can modify `issues/2.md` if it need to do.
41
42_Configuration has been omitted because it depend on each plugin._
43
44## More complexe example
45
46If you look at the [plugins.yml](../../.gitroot/plugins.yml) of GitRoot itself you will see that [apex plugin](../../plugins/name/apex.md) have a more complexe configuration:
47
48```yml
49- url: https://gitroot.dev/releases/0.3.0/apex-0.0.3.wasm
50  checksum: sha256:3f7e22f834ce7e16231f6fa08495517c1ec021cb801b9b2885345a8deb16ebf0
51  name: apex
52  active: true
53  run:
54    - path: "**/*"
55      branch:
56        - main
57      when:
58        - add
59        - mod
60        - del
61      write:
62        git:
63          - path: index.md
64            can:
65              - add
66        web:
67          - path: "**/*"
68            can:
69              - add
70              - mod
71              - del
72              - append
73      configuration: &apexConf
74        header: ...
75    - path: "**/*"
76      branch:
77        - "*"
78        - "!main"
79      when:
80        - add
81        - mod
82        - del
83      write:
84        git: []
85        web:
86          - path: branches/**/*
87            can:
88              - add
89              - mod
90              - del
91              - append
92      configuration:
93        <<: *apexConf
94        generateGitWorktree: false
95```
96
97You 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, apex plugin can only write in the `branches` directory".
98
99Why? 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 modif in an other url (e.g. http://myTld.com/myRepo/branches/brach-test/myFile) and when the change are commited to the default branche render in final destination (e.g. http://myTld.com/myRepo/myFile).