Document Git worktree (#1255)

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: Itamar Oren <itamarost@gmail.com>

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*.{py,c,cpp,h,rst,md,yml}]
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_style = space
+
+[*.{py,c,cpp,h}]
+indent_size = 4
+
+[*.rst]
+indent_size = 3
+
+[*.yml]
+indent_size = 2

.pre-commit-config.yaml

@@ -6,13 +6,13 @@ repos:
         args: [--py38-plus]
 
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 23.12.0
+    rev: 23.12.1
     hooks:
       - id: black
         args: [--skip-string-normalization]
 
   - repo: https://github.com/PyCQA/isort
-    rev: 5.13.1
+    rev: 5.13.2
     hooks:
       - id: isort
         args: [--profile=black]
@@ -21,13 +21,8 @@ repos:
     rev: 6.1.0
     hooks:
       - id: flake8
-        additional_dependencies: [flake8-2020]
-
-  - repo: https://github.com/sphinx-contrib/sphinx-lint
-    rev: v0.9.1
-    hooks:
-      - id: sphinx-lint
-        args: ["--enable=default-role"]
+        additional_dependencies:
+          [flake8-2020, flake8-implicit-str-concat]
 
   - repo: https://github.com/pre-commit/pygrep-hooks
     rev: v1.10.0
@@ -37,11 +32,24 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.5.0
     hooks:
-      - id: check-json
+      - id: check-case-conflict
       - id: check-merge-conflict
+      - id: check-json
       - id: check-yaml
+      - id: debug-statements
       - id: end-of-file-fixer
       - id: trailing-whitespace
 
+  - repo: https://github.com/sphinx-contrib/sphinx-lint
+    rev: v0.9.1
+    hooks:
+      - id: sphinx-lint
+        args: [--enable=default-role]
+
+  - repo: meta
+    hooks:
+      - id: check-hooks-apply
+      - id: check-useless-excludes
+
 ci:
   autoupdate_schedule: quarterly

getting-started/git-boot-camp.rst

@@ -669,3 +669,70 @@ Examples of useful commands:
 * Set the browser::
 
       $ gh config set browser <browser-path>
+
+
+Git worktree
+------------
+
+With Git worktrees, you can have multiple isolated working trees
+associated with a single repository (the ``.git`` directory).
+This allows you to work simultaneously on different version
+branches, eliminating the need for multiple independent clones
+that need to be maintained and updated separately.
+In addition, it reduces cloning overhead and saves disk space.
+
+Setting up Git worktree
+^^^^^^^^^^^^^^^^^^^^^^^
+
+With an existing CPython clone (see :ref:`clone-your-fork`), rename the
+``cpython`` directory to ``main`` and move it into a new ``cpython``
+directory, so we have a structure like:
+
+.. Generated with: tree -L 1 -d cpython
+
+.. code-block:: text
+
+   cpython
+   └── main (.git is here)
+
+Next, create worktrees for the other branches::
+
+   $ cd cpython/main
+   $ git worktree add -b 3.11 ../3.11 upstream/3.11
+   $ git worktree add -b 3.12 ../3.12 upstream/3.12
+
+This gives a structure like this, with the code for each branch checked out in
+its own directory:
+
+.. code-block:: text
+
+   cpython
+   ├── 3.11
+   ├── 3.12
+   └── main
+
+Using Git worktree
+^^^^^^^^^^^^^^^^^^
+
+List your worktrees, for example::
+
+   $ git worktree list
+   /Users/my-name/cpython/main  b3d24c40df [main]
+   /Users/my-name/cpython/3.11  da1736b06a [3.11]
+   /Users/my-name/cpython/3.12  cf29a2f25e [3.12]
+
+Change into a directory to work from that branch. For example::
+
+   $ cd ../3.12
+   $ git switch -c my-3.12-bugfix-branch  # create new branch
+   $ # make changes, test them, commit
+   $ git push origin my-3.12-bugfix-branch
+   $ # create PR
+   $ git switch 3.12  # switch back to the 3.12 branch
+   ...
+
+.. seealso::
+
+   * `Git Reference Manual <https://git-scm.com/docs/git-worktree>`_
+   * `"Experiment on your code freely with Git worktree"
+     <https://opensource.com/article/21/4/git-worktree>`_