deploy: 42622a7

infra/GutUsageExamples.md

@@ -1,3 +1,22 @@
+# Gut Usage Examples
+
+How to use `gut` for various operations on many `git` repositories at once.
+
+__NB!__ Note that many of the commands require at least admin access to the affected repos. Basic git operations like `clone`, `pull`, `commit` and `push` only requires read and (for push) write access.
+
+Tip: `git` supports way more commands and operations than `gut`. To apply a non-supported `git` command to a set of repos, write a simple shell script for the `git` command you need, and run it using `gut apply -r reporegex --script path/to/script.sh`. A number of example scripts can be found in `giella-core/devtools/gut-scripts/`.
+
+# Reponame regexes
+
+The core of `gut` is to run `git` commands over a set of repos with reponames matching a regex. `gut` support "extended" regexes, so one can easily match complex patterns if needed. In daily use very simple regexes are usually enough. `^` and `$` are bound to the beginning and end of the reponame.
+
+Some examples:
+
+- `-r ^lang-` — match all repos beginning with `lang-`, thus excluding the repo `template-lang-und`
+- `-r '^keyboard-s[jm]'` — match all Sámi keyboard repos
+- `-r ^corp-.*-private` — match all private corpus repos
+- `-r '^lang-(mhr|myv|fao|fin|kal|izh|kpv|fkv|olo|mdf|sje|sm.|udm|vro|mrj)$'` — match a specific set of repos
+
 # Task 1: Initialise `gut`
 
 To set up `gut` for the first time, with `giellalt` as your default organisation (so you don't have to specify it for every `gut` operation, do as follows (remember to have your GitHub Peronal access token available):
@@ -23,15 +42,15 @@ This will clone all repos in the `giellalt` org matching the regular expression
 gut clone -u -o giellalt -r ^lang
 ```
 
-# Task 3: add a new language
+# Task 3: Add a new language
 
 Description moved to a [separate page](HowToAddANewLanguage.md).
 
-# Task 4: update template, propagate changes to all matching repos
+# Task 4: Update many repos from template
 
 Description moved to a [separate page](infraremake/HowToMergeUpdatesFromCore.md).
 
-# Task 5: manage topics, info
+# Task 5: Manage topics, info
 
 ## Set topics
 
@@ -53,34 +72,34 @@ gut topic add -o giellalt -r "lang-(s|cr)" -t indigenous-languages
 gut set info -o giellalt -r "(lang-|giella-)" -w https://giellalt.uit.no
 ```
 
-# Task 6: make repo(s) public/private
+# Task 6: Make repo(s) public/private
 
 ```sh
 gut make -o giellalt -r "(lang-|giella-)" private
 ```
 
-# Task 7: add description with dynamic content
+# Task 7: Add description with dynamic content
 
 ```sh
 gut set info -o giellalt -r 'lang-XXX' --des-script giella-core/devtools/gut-scripts/reponame2description.sh
 ```
 
 **NB!** Make sure there is no trailing newline at the end of the output of the script, or it will fail. That is, use `printf`,  *not* `echo`.
 
-# Task 8: create team, and populate with users
+# Task 8: Create team, and populate with users
 
 ```sh
 gut create team -o giellalt -t "Kainun kieli" \
 -d "Team for working with the kveen language." -m Trondtr snomos
 ```
 
-# Task 9: add users to an existing team
+# Task 9: Add users to an existing team
 
 ```sh
 gut add users -o giellalt -t giellaltstaff -u ilm024 leneantonsen
 ```
 
-# Task 10: add webhook
+# Task 10: Add webhook
 
 ```sh
 gut hook create -m json -o giellalt -r 'lang-' \
@@ -123,7 +142,7 @@ gut hook create -m json -o giellalt -r 'lang-' \
 More information about the various webhook events can be found in the
 [GitHub Documentation](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/webhook-events-and-payloads).
 
-# Task 11: add external repo using `git subtree`
+# Task 11: Add external repo using `git subtree`
 
 There are a lot of FST descriptions of languages out there, one major such source is [Apertium](https://github.com/apertium). But most of these projects do not make spelling checkers or many other tools based on their morphological description. Since we have the infrastructure and the tools in place to make all languages work, it might be useful to just take those repos, and compile their fst within our infra, and from there make spellers, tokenisers, and a lot of other stuff. To do that, add a new language as follows: