📝 Update git section

* Add diff source and destination prefix
* Add diff with exiftool
* Add git list-changed
* Add default branch config for init
* Add git-symbolic-ref
* Add Git Credential Store for Linux
* Update shallow clones
* Add shell configs and command line tools
* Add aliases for faster resolution of merge conflicts
* Add pre-rebase hook for the pre-commit framework
* Add git describe
* Extend git stash section
* Update sparse checkout
* Add tag sort and prune tags
* Add options for git commit --amend
* Add tip for merge requests

Author: veit

CHANGELOG.rst

@@ -26,6 +26,19 @@ Added
 * 📝 Add csv.Sniffer methods
 * 📝 Add the removal of git lfs
 
+
+Changed
+~~~~~~~
+
+* 📝 Update git section
+
+  * Add diff source and destination prefix
+  * Add default branch config for init
+  * Add git-symbolic-ref
+  * Add Git Credential Store for Linux
+  * Update shallow clones
+  * Add shell config and command line tools
+
 `24.3.0 <https://github.com/cusyio/Python4DataScience/compare/24.2.0...24.3.0>`_: 2024-11-03
 --------------------------------------------------------------------------------------------
 

README.rst

@@ -166,11 +166,11 @@ Follow us
 Pull-Requests
 -------------
 
-If you have suggestions for improvements and additions, I recommend that you
-create a `Fork <https://github.com/cusyio/python4datascience/fork>`_ of my
+If you have suggestions for improvements and additions, we recommend that you
+create a `Fork <https://github.com/cusyio/python4datascience/fork>`_ of our
 `GitHub Repository <https://github.com/cusyio/python4datascience/>`_ and make
 your changes there. You are also welcome to make a *pull request*. If the
-changes contained therein are small and atomic, I’ll be happy to look at your
+changes contained therein are small and atomic, we will be happy to look at your
 suggestions.
 
 The following guidelines help us to maintain the German translation of the

docs/productive/git/advanced/batch.rst

@@ -24,6 +24,8 @@ Example
     changes the permissions for all files with the suffix ``.py`` from
     ``100644`` to ``100755``, if necessary, so that they become executable.
 
+.. _git-name-only:
+
 All files changed in the working or staging area
 ------------------------------------------------
 
@@ -35,9 +37,26 @@ All files changed in the working or staging area
 :samp:`git diff --staged --name-only "*.{SUFFIX}"`
     also filters for a specific file extension.
 
+.. _list-changed:
+
+:samp:`git diff --name-only --diff-filter d`
+    excludes deleted files.
+
+    This is the most common case for me, which is why I have created a
+    ``list-changed`` alias for this: ``git config --global alias.list-changed
+    'diff --name-only --diff-filter d'``.
+
 Example
 ~~~~~~~
 
-:samp:`pytest $(git diff --staged --name-only "tests/test_*.py")`
+To execute commands for the changed file list, you can use the shell `Command
+Substitution
+<https://www.gnu.org/software/bash/manual/html_node/Command-Substitution.html>`_:
+
+:samp:`$ uv run codespell $(git list-changed '*.py')`
+    The shell executes the ``git list-changed`` in brackets and inserts its
+    output into the outer command. ``codespell`` therefore receives the list of
+    changed text files as an argument.
+:samp:`uv run pytest $(git diff --staged --name-only "tests/*test_*.py")`
     calls :doc:`python-basics:test/pytest/index` to execute only those test
     modules that have been changed in the working directory.

docs/productive/git/advanced/binary-files.rst

@@ -24,16 +24,16 @@ Then we can use :doc:`pandas:reference/api/pandas.DataFrame.to_csv` in
     :language: python
 
 Now add the following section to your global Git configuration
-:file:`~/.gitconfig`:
+:file:`~/.config/git/config`:
 
 .. code-block:: ini
 
     [diff "excel"]
         textconv=python3 /PATH/TO/exceltocsv.py
         binary=true
 
-Finally, in the global :file:`~/.gitattributes` file, our ``excel`` converter is
-linked to :file:`*.xlsx` files:
+Finally, in the global :file:`~/.config/git/attributes` file, our ``excel``
+converter is linked to :file:`*.xlsx` files:
 
 .. code-block:: ini
 
@@ -56,15 +56,16 @@ For this, ``pdftohtml`` is additionally required. It can be installed with
 
       $ brew install pdftohtml
 
-Add the following section to the global Git configuration :file:`~/.gitconfig`:
+Add the following section to the global Git configuration
+:file:`~/.config/git/config`:
 
 .. code-block:: ini
 
     [diff "pdf"]
         textconv=pdftohtml -stdout
 
-Finally, in the global :file:`~/.gitattributes` file, our ``pdf`` converter is
-linked to :file:`*.pdf` files:
+Finally, in the global :file:`~/.config/git/attributes` file, our ``pdf``
+converter is linked to :file:`*.pdf` files:
 
 .. code-block:: ini
 
@@ -73,10 +74,12 @@ linked to :file:`*.pdf` files:
 Now, when ``git diff`` is called, the PDF files are first converted and then a
 diff is performed over the outputs of the converter.
 
-… for Word documents
---------------------
+.. _pandoc-to-markdown:
 
-Differences in Word documents can also be displayed. For this purpose `Pandoc
+… for documents
+---------------
+
+Differences in documents can also be displayed. For this purpose `Pandoc
 <https://pandoc.org/>`_ can be used, which can be easily installed with
 
 .. tab:: Debian/Ubuntu
@@ -97,24 +100,92 @@ Differences in Word documents can also be displayed. For this purpose `Pandoc
    <https://github.com/jgm/pandoc/releases/>`_.
 
 Then add the following section to your global Git configuration
-:file:`~/.gitconfig`:
+:file:`~/.config/git/attributes`:
 
 .. code-block:: ini
 
-    [diff "word"]
-        textconv=pandoc --to=markdown
-        binary=true
-        prompt=false
+   [diff "pandoc-to-markdown"]
+       textconv = pandoc --to markdown
+       cachetextconv = true
 
-Finally, in the global :file:`~/.gitattributes` file, our ``word`` converter is
-linked to :file:`*.docx` files:
+Finally, in the global :file:`~/.config/git/attributes` file, our
+``pandoc-to-markdown`` converter is linked to :file:`*.docx`, :file:`*.odt` and
+:file:`*.rtf` files:
 
 .. code-block:: ini
 
-    *.docx diff=word
+   *.docx diff=pandoc-to-markdown
+   *.odt diff=pandoc-to-markdown
+   *.rtf diff=pandoc-to-markdown
+
+.. tip::
+   :doc:`Jupyter Notebooks <jupyter-tutorial:notebook/index>` write to a JSON
+   file :ref:`*.ipynb <jupyter-tutorial:whats-an-ipynb-file>`, which is quite
+   dense and difficult to read, especially with diffs. The Markdown
+   representation of Pandoc simplifies this:
+
+   .. code-block:: ini
+
+      *.ipynb diff=pandoc-to-markdown
 
 The same procedure can be used to obtain useful diffs from other binaries, for
 example ``*.zip``, ``*.jar`` and other archives with ``unzip`` or for changes in
 the meta information of images with ``exiv2``. There are also conversion tools
 for converting ``*.odt``, ``*.doc`` and other document formats into plain text.
 For binary files for which there is no converter, strings are often sufficient.
+
+.. _exiftool:
+
+… for media files
+-----------------
+
+`ExifTool <https://exiftool.org>`_ can be used to convert the metadata of media
+files to text.
+
+.. tab:: Debian/Ubuntu
+
+   .. code-block:: console
+
+      $ sudo apt install libimage-exiftool-perl
+
+.. tab:: macOS
+
+   .. code-block:: console
+
+      $ brew install exiftool
+
+.. tab:: Windows
+
+   .. code-block:: ps1
+
+      > choco install exiftool
+
+.. seealso::
+   * `Installing ExifTool <https://exiftool.org/install.html>`_
+
+You can then add the following section to the global Git configuration file
+:file:`~/.config/git/config`:
+
+.. code-block:: ini
+
+   [diff "exiftool"]
+   textconv = exiftool --composite -x 'Exiftool:*'
+   cachetextconv = true
+   xfuncname = "^-.*$"
+
+Finally, in :file:`~/.config/git/attributes` the ``exiftool`` converter is
+linked to file endings of media files:
+
+.. code-block:: ini
+
+   *.avif diff=exiftool
+   *.bmp diff=exiftool
+   *.gif diff=exiftool
+   *.jpeg diff=exiftool
+   *.jpg diff=exiftool
+   *.png diff=exiftool
+   *.webp diff=exiftool
+
+.. seealso::
+   ``exiftool`` can process many more media files. You can find a complete list
+   in `Supported File Types <https://exiftool.org/#supported>`_.

docs/productive/git/advanced/delta-side-by-side-diff.png

@@ -137,7 +137,6 @@ GitHub syntax for conditions and expressions
        steps:
          - run: echo "Deploy to production server"
 
-
 GitLab syntax for conditions and expressions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/productive/git/advanced/delta.png

@@ -15,6 +15,17 @@ work on them together. Merge requests contain:
 * discussion posts
 * the list of commits
 
+.. tip::
+   If you have created a fork, do not issue the merge requests from the ``main``
+   branch. This avoids the following difficulties:
+
+   * You can then work on several merge requests instead of just one.
+   * If your merge request has been accepted, you can no longer make a ``git
+     pull`` because you have conflicting commits.
+   * If the ``main`` branch of the target repository is protected, people with
+     the maintainer role can no longer edit the merge request. All changes would
+     then have to go through you.
+
 .. seealso::
    * `Merge requests <https://docs.gitlab.com/ee/user/project/merge_requests/>`_