🎨 Improve structure of the git section

Author: veit

docs/data-processing/apis/grpc/example.rst

@@ -64,7 +64,7 @@ Generieren des gRPC-Codes
 Dies erzeugt zwei Dateien:
 
 :download:`accounts_pb2.py`
-    enthält Klassen für die in ``accounts.proto`` definierten Messages.
+    enthält Klassen für die in :file:`accounts.proto` definierten Messages.
 :download:`accounts_pb2_grpc.py`
     enthält die definierten Klassen ``AccountsStub`` für den Aufruf von RPCs,
     ``AccountsServicer`` für die API-Definition des Services und eine Funktion

docs/data-processing/nosql/key-value-store.rst

@@ -11,7 +11,8 @@ Schlüssel-Werte-Datenbanken, auch Key Value Stores genannt, speichern
 Datenbanksysteme
 ----------------
 
-Schlüssel/Wert-Datenbanksysteme sind z.B. Riak, Cassandra, Redis und MongoDB.
+Schlüssel/Wert-Datenbanksysteme sind :abbr:`z.B. (zum Beispiel)` Riak,
+Cassandra, Redis und MongoDB.
 
 +------------------------+--------------------------------+--------------------------------+--------------------------------+--------------------------------+
 | **Home**               | `Riak`_                        | `Cassandra`_                   | `Redis`_                       | `MongoDB`_                     |

docs/productive/git/advanced/hooks/advanced.rst

@@ -79,7 +79,7 @@ werden:
         :samp:`[email protected]:veit/python4datascience`
     ``$PRE_COMMIT_REMOTE_BRANCH``
         Der Name des entfernten Zweigs, zu dem gepusht wurde, :abbr:`z.B. (zum
-        Beispiel)` :samp:`refs/heads/{TARGET-BRANCH}`
+        Beispiel)` :samp:`refs/heads/{TARGET_BRANCH}`
     ``$PRE_COMMIT_LOCAL_BRANCH``
         Der Name des lokalen Zweigs, der in den entfernten Zweig verschoben
         wurde, :abbr:`z.B. (zum Beispiel)` :samp:`{HEAD}`

docs/productive/git/branch.rst

@@ -43,10 +43,10 @@ Gebräuchliche Befehle
     Mit :samp:`git config --global branch.sort -committerdate` könnt ihr diese
     Einstellung auch zu eurer Standardeinstellung machen.
 
-:samp:`$ git branch [{BRANCH_NAME}]`
+:samp:`$ git branch {BRANCH_NAME}`
     erstellt auf Basis des aktuellen ``HEAD`` einen neuen Zweig.
 
-:samp:`$ git switch [-c] [{BRANCH_NAME}]`
+:samp:`$ git switch [-c] {BRANCH_NAME}`
     wechselt zwischen Zweigen.
 
     ``-c``
@@ -63,7 +63,7 @@ Gebräuchliche Befehle
             ``-b``
                 erstellt den angegebenen Zweig, wenn dieser nicht schon besteht.
 
-:samp:`$ git merge [{FROM_BRANCH_NAME}]`
+:samp:`$ git merge {FROM_BRANCH_NAME}`
     verbindet den angegebenen mit dem aktuellen Zweig, in dem ihr euch gerade
     befindet, :abbr:`z.B. (zum Beispiel)`:
 

docs/productive/git/glossary.rst

@@ -30,16 +30,19 @@ Git-Glossar
         <https://de.wikipedia.org/wiki/Secure_Hash_Algorithm>`_.
 
     Fork
-        Kopie eines Repository auf GitLab, die einem anderen User oder einer
-        anderen Gruppe gehört.
+        Kopie eines Repository auf :term:`GitLab`, das einem anderen User oder
+        einer anderen Gruppe gehört.
 
     Git
         Git ist eine verteilte Versionsverwaltung.
 
     GitLab
         Web-Anwendung zur Versionsverwaltung auf Basis von :term:`git`. Später
-        kamen Gitlab CI, ein System zur kontinuierlichen Integration, GitLab
-        Runner, Container-Registry und vieles andere hinzu.
+        kamen :doc:`advanced/gitlab/ci-cd`, ein System zur kontinuierlichen
+        Integration, GitLab Runner, Container-Registry und vieles andere hinzu.
+
+        .. seealso::
+           * :doc:`advanced/gitlab/index`
 
     ``HEAD``
         Der ``HEAD``-Zeiger repräsentiert euer aktuelles Arbeitsverzeichnis und
@@ -53,9 +56,10 @@ Git-Glossar
 
     Merge request
         Ort zum Vergleichen und Diskutieren der in einem Branch eingeführten
-        Änderungen mit Bewertungen, Kommentaren, Tests etc.; siehe auch
-        `Merge requests
-        <https://docs.gitlab.com/ee/user/project/merge_requests/>`_.
+        Änderungen mit Bewertungen, Kommentaren, Tests :abbr:`etc. (et cetera)`;
+
+        .. seealso::
+            * :doc:`advanced/gitlab/merge-requests`.
 
     ``origin``
         Das übliche Upstream-Repository. Die meisten Projekte haben mindestens
@@ -65,16 +69,16 @@ Git-Glossar
         die ihr mit ``git branch -r`` sehen könnt.
 
     Remote Repository
-        Ein Repository, das zum Nachverfolgen eines gemeinsamen Projekt
-        verwendet wird, sich aber an einem anderen Ort befindet.
+        Gemeinsames Repository, :abbr:`z.B. (zum Beispiel)` auf :term:`GitLab`,
+        zum Austausch von Änderungen in einem Team.
 
     Trunk-Based Development
     TBD
         Git-Workflow mit kurzlebigen Themenzweigen, die schnell zum einem
         einzigen ``main``-Zweig zusammengeführt werden.
 
         .. seealso::
-           * `Trunk Based Development <https://trunkbaseddevelopment.com/>`_
+           * :doc:`workflows/tbd`
 
     Working Tree
         Der Baum der tatsächlich ausgecheckten Dateien. Der Arbeitsbaum enthält

docs/productive/git/index.rst

@@ -92,7 +92,7 @@ Zum Weiterlesen
     working-areas
     install-config
     work
-    log
+    review
     tag
     branch
     rebase

docs/productive/git/rebase.rst

@@ -30,9 +30,9 @@ folgendes:
 
 #. Im Hauptzweig wird ein Fehler in einer Funktion festgestellt, die früher
    einmal fehlerfrei funktionierte.
-#. Durch die *saubere Historie* des Hauptzweigs sollte :doc:`log` schnell
+#. Durch die *saubere Historie* des Hauptzweigs sollte :doc:`review` schnell
    Rückschlüsse ermöglichen.
-#. Sollte :doc:`log` nicht zum gewünschten Ergebnis führen, hilft vermutlich
+#. Sollte :doc:`review` nicht zum gewünschten Ergebnis führen, hilft vermutlich
    :doc:`git bisect <advanced/bisect>` weiter. Dabei hilft ``git bisect`` die
    saubere Git-Historie bei der Suche nach der Regression.
 

docs/productive/git/log.rst renamed to docs/productive/git/review.rst

@@ -2,8 +2,8 @@
 ..
 .. SPDX-License-Identifier: BSD-3-Clause
 
-``log`` und ``reflog``
-======================
+Rückblick
+=========
 
 ``log``
 -------
@@ -17,46 +17,46 @@ Filtern und sortieren
 
 .. glossary::
 
-   :samp:`git log [-n {COUNT}]`
-       auflisten der Commit-Historie des aktuellen Zweiges.
+   :samp:`$ git log [-n {COUNT}]`
+       listet die Commit-Historie des aktuellen Zweiges auf.
 
        ``-n``
            beschränkt die Anzahl der Commits auf die angegebene Zahl.
 
-   :samp:`git log [--after="{YYYY-MM-DD}"] [--before="{YYYY-MM-DD}"]`
+   :samp:`$ git log [--after="{YYYY-MM-DD}"] [--before="{YYYY-MM-DD}"]`
        Commit-Historie gefiltert nach Datum.
 
        Auch relative Angaben wie ``1 week ago`` oder ``yesterday`` sind
        zulässig.
 
-   :samp:`git log --author="{VEIT}"`
+   :samp:`$ git log --author="{VEIT}"`
        filtert die Commit-Historie nach Autor*innen.
 
        Es kann auch nach mehreren Autor*innen gleichzeitig gesucht werden,
        :abbr:`z.B. (zum Beispiel)`:
 
-       :samp:`git log --author="{VEIT\|VSC}"`
+       :samp:`$ git log --author="{VEIT\|VSC}"`
 
-   :samp:`git log --grep="{TERM}" [-i]`
+   :samp:`$ git log --grep="{TERM}" [-i]`
        filtert die Commit-Historie nach regulären Ausdrücken in der
        Commit-Nachricht.
 
        ``-i``
            ignoriert Groß- und Kleinschreibung.
 
-   :samp:`git log -S"{FOO}" [-i]`
+   :samp:`$ git log -S"{FOO}" [-i]`
        filtert Commits nach bestimmten Zeilen im Quellcode.
 
        ``-i``
            ignoriert Groß- und Kleinschreibung.
 
-   :samp:`git log -G"{BA*}"`
+   :samp:`$ git log -G"{BA*}"`
        filtert Commits nach regulären Ausdrücken im Quellcode.
 
-   :samp:`git log -- {PATH/TO/FOO.PY}`
+   :samp:`$ git log -- {PATH/TO/FILE}`
        filtert die Commit-Historie nach bestimmten Dateien.
 
-   :samp:`git log {MAIN}..{FEATURE}`
+   :samp:`$ git log {MAIN}..{FEATURE}`
        filtert nach unterschiedlichen Commits in verschiedenen Zweigen
        (Branches), in unserem Fall zwischen den Branches :samp:`MAIN` und
        :samp:`FEATURE`.
@@ -70,17 +70,17 @@ Filtern und sortieren
            \
             C - D feature
 
-       :samp:`git log {MAIN}..{FEATURE}`
+       :samp:`$ git log {MAIN}..{FEATURE}`
            zeigt Änderungen in :samp:`{FEATURE}` an, die nicht in :samp:`{MAIN}`
            enthalten sind, also die Commits ``C`` und ``D``.
-       :samp:`git log {FEATURE}..{MAIN}`
+       :samp:`$ git log {FEATURE}..{MAIN}`
            zeigt Änderungen in :samp:`{MAIN}` an, die nicht in :samp:`{FEATURE}`
            enthalten sind, also den Commit ``B``.
-       :samp:`git log {MAIN}...{FEATURE}`
+       :samp:`$ git log {MAIN}...{FEATURE}`
            zeigt die Änderungen auf beiden Seiten an, also die Commits ``B``,
            ``C`` und ``D``.
 
-   :samp:`$git log --follow {PATH/TO/FOO.PY}`
+   :samp:`$ git log --follow {PATH/TO/FILE}`
        Dies sorgt dafür, dass das Log Änderungen an einer einzelnen Datei
        anzeigt, auch wenn diese umbenannt oder verschoben wurde.
 
@@ -90,13 +90,13 @@ Filtern und sortieren
 
        .. code-block:: console
 
-          git config --global log.follow true
+          $ git config --global log.follow true
 
        Dann müsst ihr nicht mehr ``--follow`` angeben, sondern nur noch den
        Dateinamen.
 
-   :samp:`git log -L {LINE_START_INT|LINE_START_REGEX},{LINE_END_INT|LINE_END_REGEX}:{PATH/TO/FOO.PY}`
-   :samp:`git log -L :{FUNCNAME_REGEX}:{PATH/TO/FOO.PY}`
+   :samp:`$ git log -L {LINE_START_INT|LINE_START_REGEX},{LINE_END_INT|LINE_END_REGEX}:{PATH/TO/FILE}`
+   :samp:`$ git log -L :{FUNCNAME_REGEX}:{PATH/TO/FILE}`
        Mit der Option `-L
        <https://git-scm.com/docs/git-log#Documentation/git-log.txt--Lltstartgtltendgtltfilegt>`_
        könnt ihr eine verfeinerte Suche durchführen, indem ihr das Log nur eines
@@ -109,7 +109,7 @@ Filtern und sortieren
        Für umfassendere Untersuchungen könnt ihr auch mehrere Blöcke verfolgen.
        Hierfür könnt ihr mehrere ``-L``-Optionen auf einmal verwenden.
 
-   :samp:`git log --reverse`
+   :samp:`$ git log --reverse`
        Üblicherweise zeigt das Protokoll den neuesten Commit zuerst an. Ihr
        könnt dies mit ``--reverse`` umkehren. Dies ist besonders nützlich, wenn
        ihr mit den bereits erwähnten Optionen ``-S`` und ``-G`` untersucht.
@@ -122,14 +122,14 @@ Ansicht
 
 .. glossary::
 
-   :samp:`git log --stat --patch|-p`
+   :samp:`$ git log --stat --patch|-p`
        ``--stat``
            Den üblichen Metadaten wird noch eine eine Zusammenfassung der Anzahl
            der geänderten Zeilen pro Datei hinzugefügt.
        ``--patch|-p``
            ergänzt die Ausgabe um den vollständigen Commit-Diff.
 
-   :samp:`git log --oneline --decorate --graph --all|{FEATURE}`
+   :samp:`$ git log --oneline --decorate --graph --all|{FEATURE}`
        anzeigen des Verlaufsdiagramms mit Referenzen, ein Commit pro Zeile.
 
        ``--oneline``
@@ -172,7 +172,7 @@ Das Reflog für ``HEAD`` anzeigen
 
 .. glossary::
 
-   :samp:`git reflog`
+   :samp:`$ git reflog`
        Wenn keine Optionen angegeben sind, zeigt der Befehl standardmäßig das
        Reflog für ``HEAD`` an. Es ist die Abkürzung für ``git reflog show
        HEAD``. git reflog hat weitere Unterbefehle zur Verwaltung des Logs, aber

docs/productive/git/tag.rst

@@ -11,7 +11,7 @@ markiert werden, :abbr:`z.B. (zum Beispiel)` :samp:`v3.9.16`. Tags sind wie
 :doc:`branch`, die sich nicht ändern, also keine weitere Historie von Commits
 haben.
 
-:samp:`git tag {TAGNAME}`
+:samp:`$ git tag {TAGNAME}`
     erstellt einen Tag, wobei :samp:`{TAGNAME}` eine semantische Bezeichnung für
     den aktuellen Zustand des Git-Repositories ist. Dabei unterscheidet Git zwei
     verschiedene Arten von Tags: annotierte und leichtgewichtige Tags. Sie
@@ -32,7 +32,7 @@ haben.
         erstellt werden. Sie erstellen eine Tag-Prüfsumme, die im
         :file:`.git/`-Verzeichnis eures Repos gespeichert werden.
 
-:samp:`git tag`
+:samp:`$ git tag`
     listet die Tags eures Repos auf, :abbr:`z.B. (zum Beispiel)`:
 
     .. code-block:: console
@@ -43,15 +43,16 @@ haben.
         v1.1
         ...
 
-    :samp:`git tag -l '{REGEX}'`
+    :samp:`$ git tag -l '{REGEX}'`
         listet nur Tags auf, die zu einem regulären Ausdruck passen.
 
-:samp:`git tag -a {TAGNAME} {COMMIT-SHA}`
+:samp:`$ git tag -a {TAGNAME} {COMMIT-SHA}`
     erstellt einen Tag für einen früheren Commit.
 
     Die vorangegangenen Beispiele erstellen Tags für implizite Commits, die auf
     ``HEAD`` verweisen. Alternativ kann :samp:`git tag` auch die Referenz auf
-    einen bestimmten Commit übergeben werden, die ihr mit :doc:`log` erhaltet.
+    einen bestimmten Commit übergeben werden, die ihr mit :doc:`review`
+    erhaltet.
 
     Wenn ihr jedoch versucht, ein Tag mit dem gleichen Bezeichner wie ein
     bestehendes Tag zu erstellen, gibt Git eine Fehlermeldung aus, :abbr:`z.B.
@@ -67,7 +68,7 @@ haben.
         $ git tag -af v3.9.16 595f9ccb0c059f2fb5bf13643bfc0cdd5b55a422 -m 'Python 3.9.16'
         Tag 'v3.9.16' aktualisiert (war 4f5c5473ea)
 
-:samp:`git push origin {TAGNAME}`
+:samp:`$ git push origin {TAGNAME}`
     Das Teilen von Tags ist ähnlich wie der Push von Zweigen: standardmäßig
     werden mit :samp:`git push` keine Tags freigegeben, sondern sie müssen
     explizit an :samp:`git push` übergeben werden :abbr:`z.B. (zum Beispiel)`:
@@ -106,7 +107,7 @@ haben.
        * `git config push.followTags
          <https://git-scm.com/docs/git-config#Documentation/git-config.txt-pushfollowTags>`_
 
-:samp:`git checkout {TAGNAME}`
+:samp:`$ git checkout {TAGNAME}`
     wechselt in den Zustand des Repository mit diesem Tag und trennt ``HEAD`` ab.
     :abbr:`D.h. (Das heißt)`, dass alle Änderungen, die nun vorgenommen werden,
     das Tag nicht aktualisieren, sondern in einem losgelösten Commit landen, der
@@ -115,7 +116,7 @@ haben.
     wenn solche Änderungen vorgenommen werden sollen, :abbr:`z.B. (zum
     Beispiel)` mit :samp:`git checkout -b v3.9.17 v3.9.16`.
 
-:samp:`git tag -d {TAGNAME}`
+:samp:`$ git tag -d {TAGNAME}`
     löscht einen Tag, :abbr:`z.B. (zum Beispiel)`:
 
     .. code-block:: console

docs/productive/git/undo.rst

@@ -19,22 +19,22 @@ Aufgaben hat:
         In Git < 2.23 steht euch ``git restore`` noch nicht zur Verfügung. In
         diesem Fall müsst ihr noch ``git checkout`` verwenden:
 
-       :samp:`$ git checkout {FILE}`
+       :samp:`$ git checkout {PATH/TO/FILE}`
 
-    :samp:`git restore [-S|--staged] {FILE}`
+    :samp:`$ git restore [-S|--staged] {PATH/TO/FILE}`
         nimmt das Hinzufügen von Dateien zurück. Die Änderungen bleiben in eurem
         Arbeitsbereich erhalten, so dass ihr sie bei Bedarf ändern und wieder
         hinzufügen könnt.
 
-        Der Befehl entspricht :samp:`git reset {PATH}`.
+        Der Befehl entspricht :samp:`git reset {PATH/TO/PATH}`.
 
-    :samp:`git restore [-SW] {FILE}`
+    :samp:`$ git restore [-SW] {PATH/TO/FILE}`
         nimmt das Hinzufügen und Änderungen im Arbeitsbereich zurück.
-    :samp:`git restore [-s|--source] {BRANCH} {FILE}`
+    :samp:`$ git restore [-s|--source] {BRANCH} {PATH/TO/FILE}`
         setzt eine Änderung auf die Version im Zweig :samp:`{BRANCH}` zurück.
-    :samp:`git restore [-s|--source] @~ {FILE}`
+    :samp:`$ git restore [-s|--source] @~ {PATH/TO/FILE}`
         setzt eine Änderung auf den vorherigen Commit zurück.
-    :samp:`git restore [-p|--patch]`
+    :samp:`$ git restore [-p|--patch]`
         lässt euch die rückgängig zu machenden Änderungen einzeln auswählen.
 
 :samp:`$ git reset [--hard | --mixed | --soft | --keep] {TARGET_REFERENCE}`
@@ -132,7 +132,7 @@ Aufgaben hat:
            vorgesehenen Änderungen vor dem ``reset`` verwerfen will, verwende
            ich ``git restore -SW``.
 
-:samp:`$ git revert {COMMIT SHA}`
+:samp:`$ git revert {COMMIT_SHA}`
     erstellt einen neuen Commit und nimmt die Änderungen des angegebenen Commits
     zurück, sodass die Änderungen invertiert werden.
 :samp:`$ git fetch --prune {REMOTE}`