Merge pull request #28 from t4d-gmbh/26-finish-revisions-submodules-s…

…ection

26 finish revisions submodules section

source/content/submodules/gotchas.md

@@ -1,21 +1,28 @@
 ## Gotchas for <i class="fab fa-git"></i> Submodules
 
-1. **Submodules Do Not Update Automatically** ⚠️: {% if slide %}Submodules are not automatically updated to the latest commit.{% else %}When you clone a repository that contains submodules, the submodules are not automatically updated to the latest commit.
-   You need to run `git submodule update` or use the `--recurse-submodules` option when cloning to ensure they are initialized and updated.{% endif %}
+1. **Submodules Do Not Update Automatically** ⚠️:
+{% if slide %}
+Submodules are not automatically updated to the latest commit.
+{% else %}
+When you clone a repository that contains submodules, the latter are not automatically updated to the latest commit. You need to run `git submodule update` or use the `--recurse-submodules` option when cloning to ensure they are initialized and updated.
+{% endif %}
 
-2. **Repository Resides in the `.git` Folder of the Parent Repo** 🔒: The metadata for submodules is stored in the parent repository's `.git` folder.{% if page %} This means that the actual repository for the submodule is not in its own separate `.git` folder, which can lead to confusion.
-   Be cautious that providing access to the `.git` folder of the parent repository provides access to history of all its submodules!{% endif %}
+2. **Repository Resides in the `.git` Folder of the Parent Repo** 🔒: The metadata for submodules is stored in the parent repository's `.git` folder.
 {% if page %}
+This means that the actual repository for the submodule is not in its own separate `.git` folder, which can lead to confusion. Be cautious that providing access to the parent repository's `.git` folder grants access to the history of all its submodules!
 {% endif %}
-3. **Submodule Commits Are Detached** 🤔: <i class="fab fa-git"></i> submodules were designed to be pinned to a commit and not to track a branch.{% if page %} When you check out a submodule, it is in a "detached HEAD" state in most cases, meaning it is not on a branch.
-   This can be confusing if you try to make changes directly in the submodule without creating a new branch first.
+
+3. **Submodule Commits Are Detached** 🤔: <i class="fab fa-git"></i> submodules are designed to be pinned to a specific commit and do not track a branch.
+{% if page %}
+When you check out a submodule, it is usually in a "detached HEAD" state, generally meaning it is not on a branch. This can be confusing if you try to make changes directly in the submodule without creating a new branch first.
+
    :::{tip}
-   You can setup a repository to track a branch with the `-b` option:
+   You can set up a submodule to track a branch with the `-b` option:
 
    ```bash
    git submodule add -b <bname> https://gitlab.com/...
    ```
-   Or by navigating into the directory of an existing submodule (e.g. `mySub`) and running:
+   Alternatively, navigate into the directory of an existing submodule (e.g., `mySub`) and run:
    ```bash
    git checkout bname
    git branch --set-upstream=origin/bname
@@ -27,11 +34,23 @@
 
 {% endif %}
 
-4. **Submodule URLs Can Change** 🔗: {% if slide %}You might need to update the `.gitmodules` file manually.{% else %}If the URL of a submodule repository changes, you need to update the `.gitmodules` file in the parent repository.
-   Failing to do so can lead to broken links when trying to update or clone the submodule.{% endif %}
+4. **Submodule URLs Can Change** 🔗:
+{% if slide %}
+You might need to update the `.gitmodules` file manually.
+{% else %}
+If the URL of a submodule repository changes, you must update the `.gitmodules` file in the parent repository. Failing to do so can lead to broken links when trying to update or clone the submodule.
+{% endif %}
 
-5. **Cloning with Submodules Requires Extra Steps** 🛠️: {% if slide %}Remember to use the `--recurse-submodule` option when cloning.{% else %}When cloning a repository with submodules, you need to remember to use the `--recurse-submodules` option or run `git submodule init` and `git submodule update` afterward.
-   Forgetting these steps can lead to missing submodule content.{% endif %}
+5. **Cloning with Submodules Requires Extra Steps** 🛠️:
+{% if slide %}
+Remember to use the `--recurse-submodule` option when cloning.
+{% else %}
+When cloning a repository with submodules, you need to use the `--recurse-submodules` option or run `git submodule init` and `git submodule update` afterward. Forgetting these steps can lead to missing submodule content.
+{% endif %}
 
-6. **Submodules Can Increase Complexity** 🌀: {% if slide %}Might be confusing for newcomers.{%else%}Using submodules can add complexity to your project structure.
-   If not managed properly, it can lead to confusion about which version of a submodule is being used and how it relates to the parent repository.{% endif %}
+6. **Submodules Can Increase Complexity** 🌀:
+{% if slide %}
+This might be confusing for newcomers.
+{%else%}
+Using submodules can add complexity to your project structure. If not managed properly, it can lead to confusion about which version of a submodule is being used and how it relates to the parent repository.
+{% endif %}

source/content/submodules/what_are_submodules.md

@@ -1,4 +1,4 @@
-## What are <i class="fab fa-git"></i> submodules <i class="fa-solid fa-folder-tree"></i>?
+## What are <i class="fab fa-git"></i> Submodules <i class="fa-solid fa-folder-tree"></i>?
 
 A <i class="fab fa-git"></i> submodule is essentially a repository embedded within another repository. 
 It allows you to include and manage external repositories within your main project. 
@@ -10,20 +10,18 @@ Once a submodule is initialized and updated, its content appears as a regular fo
 
 {% if page %}
 
-### Why would you need that?
+### Why are Submodules Useful?
 
-Sometimes, when you're working on a project, you might need to use another project within it.
-This could be a library created by someone else or one that you're developing separately to use in multiple projects.
-A common challenge in these situations is wanting to keep the two projects separate while still being able to use one inside the other.
+When working on a project, you may need to incorporate another project, such as a library developed by someone else or a tool you're building for use in multiple projects.
+A common challenge in these situations is maintaing separation between the two projects separate while being able to use one with the other.
 
-For example, imagine you're conducting research and have previously developed a data analysis tool for another project.
-Now, you want to use that same tool in your current research project.
-You could either copy the code from the old project into your new one or include it from a shared source.
+For example, imagine you're conducting research and want to use a data analysis tool you previously developed for another project.
+You have two options: you could copy the code from the old project into your new one, or you could include it from a shared source. 
 The problem with copying the code is that if you make any changes, it can be difficult to merge those changes back into the original tool later.
-On the other hand, if you include it from a shared source, it can be hard to customize and ensure that everyone involved in the research has access to it.
+Conversely, including it from a shared source may limit your ability to customize it, and ensuring that all collaborators have access to it can be challenging.
 
 <i class="fab fa-git"></i> addresses this issue with something called submodules.
-Submodules let you keep an <i class="fab fa-git"></i> repository as a subfolder of another <i class="fab fa-git"></i> repository.
-This allows you to selectively include specific versions of external repositories within your main project.
-This is particularly useful for incorporating your own tools or third-party resources that are maintained separately, while still keeping your changes separate.
+Submodules allow you to keep a <i class="fab fa-git"></i> repository as a subfolder within another <i class="fab fa-git"></i> repository.
+This setup enables you to selectively include specific versions of external repositories in your main project.
+This is particularly useful for incorporating your own tools or third-party resources that are maintained separately, while allowing you to keep your changes separate.
 {% endif %}

source/content/submodules/working_with.md

@@ -1,7 +1,19 @@
-### Working with <i class="fab fa-git"></i> Submodules
+## Working with <i class="fab fa-git"></i> Submodules
 
-{% if slide %}- First **checkout a branch in the submodule**, as it is usually in "detached HEAD" mode.{%else%}Just do not forget that a submodule usually does not track a branch, so **before you start working in a submodule checkout the branch you want to work on**!{% endif %}
+{% if slide %}
+- First **checkout a branch in the submodule** since it typically operates in "detached HEAD" mode.
+{%else%}
+Remember that a submodule usually does not track a branch, so **before you start working in a submodule, checkout the branch you want to work on**!
+{% endif %}
 
-{% if slide %}- Inside a submodule folder **work as if it were an ordinary <i class="fab fa-git"></i> repository**.{%else%}Once the submodule is initialized, you can **work inside the submodule folder as if it were an ordinary <i class="fab fa-git"></i> repository**.{% endif %}
+{% if slide %}
+- Inside a submodule folder **work as if it were an ordinary <i class="fab fa-git"></i> repository**.
+{%else%}
+Once the submodule is initialized, you can **work inside the submodule folder as if it were an ordinary <i class="fab fa-git"></i> repository**.
+{% endif %}
 
-{% if slide %}- To **update the tracked commit** for a submodule, check out the desired commit and then **add the submodule's path to a commit in the parent repository**.{%else%}After making any changes in a submodule, simply **add the path to the submodule to a commit** in the parent repository to **update the commit that the parent repository should track**.{% endif %}
+{% if slide %}
+- To **update the tracked commit** for a submodule, check out the desired commit and then **add the submodule's path to a commit in the parent repository**.
+{%else%}
+After making any changes in a submodule, simply **add the path to the submodule to a commit** in the parent repository to **update the commit that the parent repository should track**.
+{% endif %}