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: https://gitroot.dev/releases/0.3.0/ladybug-0.0.3.wasm
 2  checksum: sha256:adfaf88dc15ca5d53019ff194a32abec9c914c6cdf676ef4de589c1a4cfd12d4
 3  name: ladybug
 4  active: true
 5  run:
 6    - path: issues/**/*.md
 7      branch:
 8        - "*"
 9      when:
10        - add
11        - mod
12      write:
13        git:
14          - path: issues/**/*.md
15            can:
16              - mod
17        web: []
18      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: https://gitroot.dev/releases/0.3.0/apex-0.0.3.wasm
 2  checksum: sha256:3f7e22f834ce7e16231f6fa08495517c1ec021cb801b9b2885345a8deb16ebf0
 3  name: apex
 4  active: true
 5  run:
 6    - path: "**/*"
 7      branch:
 8        - main
 9      when:
10        - add
11        - mod
12        - del
13      write:
14        git:
15          - path: index.md
16            can:
17              - add
18        web:
19          - path: "**/*"
20            can:
21              - add
22              - mod
23              - del
24              - append
25      configuration: &apexConf
26        header: ...
27    - path: "**/*"
28      branch:
29        - "*"
30        - "!main"
31      when:
32        - add
33        - mod
34        - del
35      write:
36        git: []
37        web:
38          - path: branches/**/*
39            can:
40              - add
41              - mod
42              - del
43              - append
44      configuration:
45        <<: *apexConf
46        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, apex plugin can only write in the branches directory”.

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