🎨 Improve structure of the git section

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

@@ -76,7 +76,7 @@ before commits; they can also be used for other Git hooks:
         :samp:`[email protected]:veit/python4datascience`
     ``$PRE_COMMIT_REMOTE_BRANCH``
         The name of the remote branch that was pushed to, for example
-        :samp:`refs/heads/{TARGET-BRANCH}`.
+        :samp:`refs/heads/{TARGET_BRANCH}`.
     ``$PRE_COMMIT_LOCAL_BRANCH``
         The name of the local branch that was pushed to the remote branch, for
         example :samp:`{HEAD}`.

docs/productive/git/branch.rst

@@ -19,10 +19,10 @@ Git branches
     You can also use :samp:`git config --global branch.sort -committerdate` to
     make this setting your default setting.
 
-:samp:`$ git branch [{BRANCH_NAME}]`
+:samp:`$ git branch {BRANCH_NAME}`
     creates a new branch based on the current ``HEAD``.
 
-:samp:`$ git switch [-c] [{BRANCH_NAME}]`
+:samp:`$ git switch [-c] {BRANCH_NAME}`
     switches between branches.
 
     ``-c``
@@ -39,7 +39,7 @@ Git branches
             ``-b``
                 creates the specified branch if it does not already exist.
 
-:samp:`$ git merge [{FROM_BRANCH_NAME}]`
+:samp:`$ git merge {FROM_BRANCH_NAME}`
     connects the given branch with the current branch you are currently in, for
     example:
 

docs/productive/git/index.rst

@@ -90,7 +90,7 @@ the other hand :doc:`best practices <best-practices>` and typical
     working-areas
     install-config
     work
-    log
+    review
     tag
     branch
     rebase

docs/productive/git/install-config.rst

@@ -19,7 +19,8 @@ For iX distributions, Git should be in the standard repository.
 
       $ sudo apt install git-all
 
-    To install only Git the `git <https://packages.debian.org/stable/git>`_ package suffices:
+   To install only Git the `git <https://packages.debian.org/stable/git>`_
+   package suffices:
 
    .. code-block:: console
 

docs/productive/git/rebase.rst

@@ -26,9 +26,9 @@ following:
 
 #. An error is found in the main branch in a function that once worked without
    errors.
-#. With the *clean history* of the main branch, :doc:`log` should allow for
+#. With the *clean history* of the main branch, :doc:`review` should allow for
    quick conclusions.
-#. If :doc:`log` does not lead to the desired result, :doc:`git bisect
+#. If :doc:`review` does not lead to the desired result, :doc:`git bisect
    <advanced/bisect>` will probably help. In this case, the clean Git history
    helps ``git bisect`` in the search for the regression.
 

docs/productive/git/log.rst → docs/productive/git/review.rst

@@ -2,8 +2,8 @@
 ..
 .. SPDX-License-Identifier: BSD-3-Clause
 
-``log`` and ``reflog``
-======================
+Review
+======
 
 ``log``
 -------
@@ -17,45 +17,45 @@ Filter and sort
 
 .. glossary::
 
-   :samp:`git log [-n {COUNT}]`
-       list the commit history of the current branch.
+   :samp:`$ git log [-n {COUNT}]`
+       lists the commit history of the current branch.
 
        ``-n``
            limits the number of commits to the specified number.
 
-   :samp:`git log [--after="{YYYY-MM-DD}"] [--before="{YYYY-MM-DD}"]`
+   :samp:`$ git log [--after="{YYYY-MM-DD}"] [--before="{YYYY-MM-DD}"]`
        Commit history filtered by date.
 
        Relative specifications such as ``1 week ago`` or ``yesterday`` are also
        permitted.
 
-   :samp:`git log --author="{VEIT}"`
+   :samp:`$ git log --author="{VEIT}"`
        filters the commit history by author.
 
        It is also possible to search for several authors at the same time, for
        example:
 
-       :samp:`git log --author="{VEIT\|VSC}"`
+       :samp:`$ git log --author="{VEIT\|VSC}"`
 
-   :samp:`git log --grep="{TERM}" [-i]`
+   :samp:`$ git log --grep="{TERM}" [-i]`
        filters the commit history for regular expressions in the commit message.
 
        ``-i``
            ignores upper and lower case.
 
-   :samp:`git log -S"{FOO}" [-i]`
+   :samp:`$ git log -S"{FOO}" [-i]`
        filters commits for specific lines in the source code.
 
        ``-i``
            ignores upper and lower case.
 
-   :samp:`git log -G"{BA*}"`
+   :samp:`$ git log -G"{BA*}"`
        filters commits for regular expressions in the source code.
 
-   :samp:`git log -- {PATH/TO/FOO.PY}`
+   :samp:`$ git log -- {PATH}`
        filters the commit history for specific files.
 
-   :samp:`git log {MAIN}..{FEATURE}`
+   :samp:`$ git log {MAIN}..{FEATURE}`
        filters for different commits in different branches, in our case between
        the :samp:`MAIN` and :samp:`FEATURE` branches.
 
@@ -68,17 +68,17 @@ Filter and sort
            \
             C - D feature
 
-       :samp:`git log {MAIN}..{FEATURE}`
+       :samp:`$ git log {MAIN}..{FEATURE}`
            shows changes in :samp:`{FEATURE}` that are not contained in
            :samp:`{MAIN}`, that is, commits ``C`` and ``D``.
-       :samp:`git log {FEATURE}..{MAIN}`
+       :samp:`$ git log {FEATURE}..{MAIN}`
            shows changes in :samp:`{MAIN}` that are not contained in
            :samp:`{FEATURE}`, that is, commit ``B``.
-       :samp:`git log {MAIN}...{FEATURE}`
+       :samp:`$ git log {MAIN}...{FEATURE}`
            shows the changes on both sides, that is, commits ``B``, ``C`` and
            ``D``.
 
-   :samp:`$git log --follow {PATH/TO/FOO.PY}`
+   :samp:`$ git log --follow {PATH/TO/FILE}`
        This ensures that the log shows changes to a single file, even if it has
        been renamed or moved.
 
@@ -87,12 +87,12 @@ Filter and sort
 
        .. code-block:: console
 
-          git config --global log.follow true
+          $ git config --global log.follow true
 
        Then you no longer have to enter ``--follow``, but only the file name.
 
-   :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}`
        With the `-L
        <https://git-scm.com/docs/git-log#Documentation/git-log.txt--Lltstartgtltendgtltfilegt>`_
        option, you can perform a refined search by checking the log of only part
@@ -104,7 +104,7 @@ Filter and sort
            For more comprehensive investigations, you can also track multiple
            blocks. You can use multiple ``-L`` options at once.
 
-   :samp:`git log --reverse`
+   :samp:`$ git log --reverse`
        The log usually displays the latest commit first. You can reverse this
        with ``--reverse``. This is particularly useful if you are analysing with
        the ``-S`` and ``-G`` options already mentioned. By reversing the order
@@ -116,14 +116,14 @@ View
 
 .. glossary::
 
-   :samp:`git log --stat --patch|-p`
+   :samp:`$ git log --stat --patch|-p`
        ``--stat``
            A summary of the number of changed lines per file is added to the
            usual metadata.
        ``--patch|-p``
            adds the complete commit diff to the output.
 
-   :samp:`git log --oneline --decorate --graph --all|{FEATURE}`
+   :samp:`$ git log --oneline --decorate --graph --all|{FEATURE}`
        display the history graph with references, one commit per line.
 
        ``--oneline``
@@ -164,7 +164,7 @@ Show the reflog for ``HEAD``
 
 .. glossary::
 
-   :samp:`git reflog`
+   :samp:`$ git reflog`
        If no options are specified, the command displays the reflog for ``HEAD``
        by default. It is short for ``git reflog show HEAD``. git reflog has
        other subcommands to manage the log, but show is the default command if

docs/productive/git/tag.rst

@@ -10,7 +10,7 @@ allows certain points in the history to be marked for a particular version, for
 example :samp:`v3.9.16`. Tags are like :doc:`branch` that do not change, so have
 no further history of commits.
 
-:samp:`git tag {TAGNAME}`
+:samp:`$ git tag {TAGNAME}`
     creates a tag, where :samp:`{TAGNAME}` is a semantic label for the current
     state of the Git repository. Git distinguishes between two different types
     of tags: annotated and lightweight tags. They differ in the amount of
@@ -29,7 +29,7 @@ no further history of commits.
         They create a tag checksum that are stored in the :file:`.git/`
         directory of your repo.
 
-:samp:`git tag`
+:samp:`$ git tag`
     lists the tags of your repo, for example:
 
     .. code-block:: console
@@ -40,15 +40,15 @@ no further history of commits.
         v1.1
         ...
 
-    :samp:`git tag -l '{REGEX}'`
+    :samp:`$ git tag -l '{REGEX}'`
         lists only tags that match a regular expression.
 
-:samp:`git tag -a {TAGNAME} {COMMIT-SHA}`
+:samp:`$ git tag -a {TAGNAME} {COMMIT-SHA}`
     creates a tag for a previous commit.
 
     The previous examples create tags for implicit commits that reference
     ``HEAD``. Alternatively, :samp:`git tag` can be passed the reference to a
-    specific commit that you get with :doc:`log`.
+    specific commit that you get with :doc:`review`.
 
     However, if you try to create a tag with the same identifier as an existing
     tag, Git will give you an error message, for example :samp:`Fatal: tag
@@ -63,7 +63,7 @@ no further history of commits.
         $ git tag -af v3.9.16 595f9ccb0c059f2fb5bf13643bfc0cdd5b55a422 -m 'Python 3.9.16'
         Tag 'v3.9.16' updated (was 4f5c5473ea)
 
-:samp:`git push origin {TAGNAME}`
+:samp:`$ git push origin {TAGNAME}`
     Sharing tags is similar to pushing branches: by default, :samp:`git push`
     does not share tags, but they must be explicitly passed to :samp:`git push
     for example`:
@@ -101,15 +101,15 @@ no further history of commits.
        * `git config push.followTags
          <https://git-scm.com/docs/git-config#Documentation/git-config.txt-pushfollowTags>`_
 
-:samp:`git checkout {TAGNAME}`
+:samp:`$ git checkout {TAGNAME}`
     switches to the state of the repo with this tag and detaches ``HEAD``. This
     means that any changes made now will not update the tag, but will end up in
     a detached commit that cannot be part of a branch and will only be directly
     accessible via the SHA hash of the commit. Therefore, a new branch is
     usually created when such changes are to be made, for example with
     :samp:`git checkout -b v3.9.17 v3.9.16`.
 
-:samp:`git tag -d {TAGNAME}`
+:samp:`$ git tag -d {TAGNAME}`
     deletes a tag, for example:
 
     .. code-block:: console

docs/productive/git/undo.rst

@@ -20,19 +20,19 @@ this task was performed by ``git reset``, which also has other tasks:
 
        :samp:`$ git checkout {FILE}`
 
-    :samp:`git restore [-S|--staged] {FILE}`
+    :samp:`$ git restore [-S|--staged] {PATH/TO/FILE}`
         undoes the addition of files. The changes are retained in your workspace
         so that you can change and add them again if necessary.
 
-        The command is equivalent to :samp:`git reset {PATH}`.
+        The command is equivalent to :samp:`$ git reset {PATH/TO/FILE}`.
 
-    :samp:`git restore [-SW] {FILE}`
+    :samp:`$ git restore [-SW] {FILE}`
         undoes the addition and changes in the workspace.
-    :samp:`git restore [-s|--source] {BRANCH} {FILE}`
+    :samp:`$ git restore [-s|--source] {BRANCH} {FILE}`
         restores a change to the version in the :samp:`{BRANCH}`.
-    :samp:`git restore [-s|--source] @~ {FILE}`
+    :samp:`$ git restore [-s|--source] @~ {FILE}`
         restores a change to the previous commit.
-    :samp:`git restore [-p|--patch]`
+    :samp:`$ git restore [-p|--patch]`
         lets you select the changes to be undone individually.
 
 :samp:`$ git reset [--hard | --mixed | --soft | --keep] {TARGET_REFERENCE}`
@@ -123,7 +123,7 @@ this task was performed by ``git reset``, which also has other tasks:
            I want to discard all uncommitted changes before the ``reset``, I use
            ``git restore -SW``.
 
-:samp:`$ git revert {COMMIT SHA}`
+:samp:`$ git revert {COMMIT_SHA}`
     creates a new commit and reverts the changes of the specified commit so that
     the changes are inverted.
 :samp:`$ git fetch --prune {REMOTE}`

docs/productive/git/work.rst

@@ -11,10 +11,10 @@ Start working on a project
 Start your own project
 ~~~~~~~~~~~~~~~~~~~~~~
 
-:samp:`$ git init {MY_PROJECT}`
+:samp:`$ git init [{PROJECT}]`
     creates a new, local git repository.
 
-    :samp:`{MY_PROJECT}`
+    :samp:`[{PROJECT}]`
         if the project name is given, Git creates a new directory and
         initializes it.
 
@@ -49,16 +49,16 @@ Work on a project
        `git status -v
        <https://git-scm.com/docs/git-status#Documentation/git-status.txt--v>`_
 
-:samp:`$ git add {FILE}`
-    adds a file to the stage area.
+:samp:`$ git add {PATH}`
+    adds one or more files to the stage area.
 
-    :samp:`-p {FILE}`
-        adds parts of a file to the stage area.
-    :samp:`-e {FILE}`
+    :samp:`-p`
+        adds parts of one or more files to the stage area.
+    :samp:`-e`
         the changes to be adopted can be edited in the standard editor.
 
-:samp:`$ git diff {FILE}`
-    shows differences between work and stage areas, for example:
+:samp:`$ git diff [{PATH}]`
+    shows differences between working and stage areas, for example:
 
     .. code-block:: console
 
@@ -124,20 +124,19 @@ Work on a project
         :samp:`$ git checkout {FILE}`
 
 ``$ git commit``
-    make a new commit with the added changes.
+    makes a new commit with the added changes.
 
-    ``-m 'Commit message'``
-        write a commit message directly in the command line.
+    ``-m 'COMMIT MESSAGE'``
+        writes a commit message directly from the command line.
     ``--dry-run --short``
         shows what would be committed with the status in short format.
 
-
-``$ git reset [--hard|--soft] [target-reference]``
+``$ git reset [--hard|--soft] [TARGET_REFERENCE]``
     resets the history to an earlier commit.
-:samp:`$ git rm {FILE}`
+:samp:`$ git rm {PATH}`
     removes a file from the work and stage areas.
 ``$ git stash``
-    moves the current changes from the work area to the stash.
+    moves the current changes from the workspace to a stash.
 
     To be able to distinguish your hidden changes as well as possible, the
     following two options are recommended:
@@ -202,16 +201,16 @@ Work on a project
     ``-u UNTRACKED_FILE``
         hides unversioned files.
     ``list``
-        lists the hidden changes.
+        lists the various stashes.
     ``show``
-        shows the changes in the hidden files.
+        shows the changes in the stashed files.
     ``pop``
-        transfer the changes from the hiding place to the work area and empty
-        the hiding place, for example:
+        transfers the changes from the stash to the workspace and empties the
+        stash, for example:
 
         .. code-block:: console
 
-            git stash pop stash@{2}
+           $ git stash pop stash@{2}
 
     ``drop``
         empties a specific stash, for example: