From 76b36ad4f9b463b9c47f5bc2c545b888316f05a7 Mon Sep 17 00:00:00 2001
From: Magnus Hagdorn <magnus.hagdorn@charite.de>
Date: Thu, 25 Jul 2024 14:04:17 +0200
Subject: [PATCH] merge instructions on bibliography

---
 README.md | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 9b96d5e..3bc52f3 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,41 @@ python3 -m pip install -r requirements.txt
 
 ### Bibliography
 
-We use a single, shared BibTeX bibliography file for all papers in the teaching RSE project. This is imported as a Git submodule from [another repository](https://github.com/the-teachingRSE-project/bibliography). See the instructions in that repository if you need to add bibliography entries.
+We use a single, shared BibTeX bibliography file for all papers in the teaching RSE project.
+This is imported as a git submodule from [another repository](https://github.com/the-teachingRSE-project/bibliography).
+See the instructions in that repository if you need to add bibliography entries.
+
+When you first clone this repository, the bibtex folder is empty.
+To download the bibliography, run the following commands:
+
+```sh
+git submodule update --init --recursive
+git config --local submodule.recurse true
+```
+
+This will populate the folder with the contents of the remote bibliography repository.
+To modify the bibliography, you need to clone
+[the-teachingRSE-project/bibliography](https://github.com/the-teachingRSE-project/bibliography),
+commit your changes and push them. Then you can synchronize the
+local bibliography submodule by running the following commands:
+
+```sh
+git submodule update --remote bibliography
+git add bibliography
+git commit -m 'Synchronize bibliography'
+```
+
+If the remote bibliography repository is broken, you can roll back the bibliography version
+in the submodule. For example to go back 4 commits in the past, run:
+
+```sh
+cd bibliography/
+git reset HEAD~4
+git checkout .
+cd ..
+git add bibliography/
+git commit -m 'Roll back to an older version of the bibliography'
+```
 
 ### How to create a pull request