Plugin rights

Plugins 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.

First example

Taking ladybug as an example:

 1- url: plugins/ladybug/ladybug-0.0.1.wasm
 2  name: ladybug
 3  active: true
 4  run:
 5    - path: issues/**/*.md
 6      branch:
 7        - "*"
 8      when:
 9        - add
10        - mod
11      write:
12        git:
13          - path: issues/**/*.md
14            can:
15              - mod
16        web: []
17      configuration: ...

You 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.”

But it can’t create a file in git or write in web.

Be carrefull, the plugin will be called for modification of issues/1.md, but it can modify issues/2.md if it need to do.

Configuration has been omitted because it depend on each plugin.

More complexe example

If you look at the plugins.yml of GitRoot itself you will see that apex plugin have a more complexe configuration:

 1- url: plugins/apex/apex-0.0.1.wasm
 2  name: apex
 3  active: true
 4  run:
 5    - path: "**/*"
 6      branch:
 7        - main
 8      when:
 9        - add
10        - mod
11        - del
12      write:
13        git:
14          - path: index.md
15            can:
16              - add
17        web:
18          - path: "**/*"
19            can:
20              - add
21              - mod
22              - del
23              - append
24      configuration: &apexConf
25        header: ...
26    - path: "grafts/*"
27      branch:
28        - "*"
29        - "!main"
30      when:
31        - add
32        - mod
33        - del
34      write:
35        git: []
36        web:
37          - path: "grafts/*"
38            can:
39              - add
40              - append
41      configuration:
42        <<: *apexConf
43        generateGitWorktree: false

You 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.”

Why? 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.

But 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.