From f868eca93890f1fea9cb22ec340a0bf0a315f82e Mon Sep 17 00:00:00 2001
From: Timo <toger5@hotmail.de>
Date: Tue, 25 Mar 2025 20:12:36 +0100
Subject: [PATCH] Add docs and git hooks

---
 .githooks/post-commit | 11 +++++++++++
 .githooks/pre-commit  | 12 ++++++++++++
 README.md             |  4 ++++
 docs/linking.md       | 27 +++++++++++++++++++++++++++
 4 files changed, 54 insertions(+)
 create mode 100755 .githooks/post-commit
 create mode 100755 .githooks/pre-commit

diff --git a/.githooks/post-commit b/.githooks/post-commit
new file mode 100755
index 00000000..461200a2
--- /dev/null
+++ b/.githooks/post-commit
@@ -0,0 +1,11 @@
+#!/usr/bin/sh
+
+FILE=.links.disabled.yaml
+if test -f "$FILE"; then
+  # echo "$FILE exists. -> moving to .links.disabled.yaml"
+  mv .links.disabled.yaml .links.yaml
+  # echo "running yarn"
+  yarnLog=$(yarn)
+  echo "The post-commit hook enabled the links again: moved .links.disabled.yaml to .links.yaml and ran yarn."
+  exit 1
+fi
\ No newline at end of file
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
new file mode 100755
index 00000000..8d776e9c
--- /dev/null
+++ b/.githooks/pre-commit
@@ -0,0 +1,12 @@
+#!/usr/bin/sh
+
+FILE=".links.yaml"
+if test -f "$FILE"; then
+  # echo "$FILE exists. -> moving to .links.disabled.yaml"
+  mv .links.yaml .links.disabled.yaml
+  # echo "running yarn"
+  x=$(yarn)
+  y=$(git add yarn.lock)
+  echo "YARN-LINKER-HOOK: We do not allow to commit with local links in the yarn.lock file. The pre-commit hook MODIFIED the yarn.lock file with disabled .links.yaml. Check the new git status (the hook added yarn.lock, was this desired?). The post-commit hook enables the links again. It moves .links.disabled.yaml to .links.yaml and runs yarn. Run \`git commit\` again!"
+  exit 1
+fi
diff --git a/README.md b/README.md
index 8599521d..e1f56275 100644
--- a/README.md
+++ b/README.md
@@ -169,6 +169,10 @@ You're now ready to launch the development server:
 yarn dev
 ```
 
+See also:
+
+- [Developing with linked packages](./linking.md)
+
 ### Backend
 
 A docker compose file `dev-backend-docker-compose.yml` is provided to start the
diff --git a/docs/linking.md b/docs/linking.md
index dd2baa87..0abbc73e 100644
--- a/docs/linking.md
+++ b/docs/linking.md
@@ -10,3 +10,30 @@ matrix-js-sdk: ../path/to/matrix-js-sdk
 ```
 
 Then run `yarn install`.
+
+## Hooks
+
+Changes in `.links.yaml` will also update `yarn.lock` when `yarn` is executed. The lockfile will then contain the local
+version of the package which would not work on others dev setups or the github CI.
+One always needs to run:
+
+```bash
+mv .links.yaml .links.disabled.yaml
+yarn
+```
+
+before committing a change.
+
+To make it more convenient to work with this linking system we added git hooks for your conviniece.
+A `pre-commit` hook will run `mv .links.yaml .links.disabled.yaml`, `yarn` and `git add yarn.lock` if it detects
+a `.links.yaml` file and abort the commit.
+You will than need to check if the resulting changes are appropriate and commit again.
+
+A `post-commit` hook will setup the linking as it was
+before if a `.links.disabled.yaml` is present. It runs `mv .links.disabled.yaml .links.yaml` and `yarn`.
+
+To activate the hooks automatically configure git with
+
+```bash
+git config --local core.hooksPath .githooks/
+```