8000 Document Git worktree (#1255) · python/devguide@bcd0c8a · GitHub
[go: up one dir, main page]
Skip to content

Commit bcd0c8a

Browse files
hugovkezio-melottiitamaro
authored
Document Git worktree (#1255)
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com> Co-authored-by: Itamar Oren <itamarost@gmail.com>
1 parent 26f5ffc commit bcd0c8a

File tree

3 files changed

+100
-10
lines changed

3 files changed

+100
-10
lines changed

‎.editorconfig

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
root = true
2+
3+
[*.{py,c,cpp,h,rst,md,yml}]
4+
trim_trailing_whitespace = true
5+
insert_final_newline = true
6+
indent_style = space
7+
8+
[*.{py,c,cpp,h}]
9+
indent_size = 4
10+
11+
[*.rst]
12+
indent_size = 3
13+
14+
[*.yml]
15+
indent_size = 2

‎.pre-commit-config.yaml

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,13 @@ repos:
66
args: [--py38-plus]
77

88
- repo: https://github.com/psf/black-pre-commit-mirror
9-
rev: 23.12.0
9+
rev: 23.12.1
1010
hooks:
1111
- id: black
1212
args: [--skip-string-normalization]
1313

1414
- repo: https://github.com/PyCQA/isort
15-
rev: 5.13.1
15+
rev: 5.13.2
1616
hooks:
1717
- id: isort
1818
args: [--profile=black]
@@ -21,13 +21,8 @@ repos:
2121
rev: 6.1.0
2222
hooks:
2323
- id: flake8
24-
additional_dependencies: [flake8-2020]
25-
26-
- repo: https://github.com/sphinx-contrib/sphinx-lint
27-
rev: v0.9.1
28-
hooks:
29-
- id: sphinx-lint
30-
args: ["--enable=default-role"]
24+
additional_dependencies:
25+
[flake8-2020, flake8-implicit-str-concat]
3126

3227
- repo: https://github.com/pre-commit/pygrep-hooks
3328
rev: v1.10.0
@@ -37,11 +32,24 @@ repos:
3732
- repo: https://github.com/pre-commit/pre-commit-hooks
3833
rev: v4.5.0
3934
hooks:
40-
- id: check-json
35+
- id: check-case-conflict
4136
- id: check-merge-conflict
37+
- id: check-json
4238
- id: check-yaml
39+
- id: debug-statements
4340
- id: end-of-file-fixer
4441
- id: trailing-whitespace
4542

43+
- repo: https://github.com/sphinx-contrib/sphinx-lint
44+
rev: v0.9.1
45+
hooks:
46+
- id: sphinx-lint
47+
args: [--enable=default-role]
48+
49+
- repo: meta
50+
hooks:
51+
- id: check-hooks-apply
52+
- id: check-useless-excludes
53+
4654
ci:
4755
autoupdate_schedule: quarterly

‎getting-started/git-boot-camp.rst

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -669,3 +669,70 @@ Examples of useful commands:
669669
* Set the browser::
670670

671671
$ gh config set browser <browser-path>
672+
673+
674+
Git worktree
675+
------------
676+
677+
With Git worktrees, you can have multiple isolated working trees
678+
associated with a single repository (the ``.git`` directory).
679+
This allows you to work simultaneously on different version
680+
branches, eliminating the need for multiple independent clones
681+
that need to be maintained and updated separately.
682+
In addition, it reduces cloning overhead and saves disk space.
683+
684+
Setting up Git worktree
685+
^^^^^^^^^^^^^^^^^^^^^^^
686+
687+
With an existing CPython clone (see :ref:`clone-your-fork`), rename the
688+
``cpython`` directory to ``main`` and move it into a new ``cpython``
689+
directory, so we have a structure like:
690+
691+
.. Generated with: tree -L 1 -d cpython
692+
693+
.. code-block:: text
694+
695+
cpython
696+
└── main (.git is here)
697+
698+
Next, create worktrees for the other branches::
699+
700+
$ cd cpython/main
701+
$ git worktree add -b 3.11 ../3.11 upstream/3.11
702+
$ git worktree add -b 3.12 ../3.12 upstream/3.12
703+
704+
This gives a structure like this, with the code for each branch checked out in
705+
its own directory:
706+
707+
.. code-block:: text
708+
709+
cpython
710+
├── 3.11
711+
├── 3.12
712+
└── main
713+
714+
Using Git worktree
715+
^^^^^^^^^^^^^^^^^^
716+
717+
List your worktrees, for example::
718+
719+
$ git worktree list
720+
/Users/my-name/cpython/main b3d24c40df [main]
721+
/Users/my-name/cpython/3.11 da1736b06a [3.11]
722+
/Users/my-name/cpython/3.12 cf29a2f25e [3.12]
723+
724+
Change into a directory to work from that branch. For example::
725+
726+
$ cd ../3.12
727+
$ git switch -c my-3.12-bugfix-branch # create new branch
728+
$ # make changes, test them, commit
729+
$ git push origin my-3.12-bugfix-branch
730+
$ # create PR
731+
$ git switch 3.12 # switch back to the 3.12 branch
732+
...
733+
734+
.. seealso::
735+
736+
* `Git Reference Manual <https://git-scm.com/docs/git-worktree>`_
737+
* `"Experiment on your code freely with Git worktree"
738+
<https://opensource.com/article/21/4/git-worktree>`_

0 commit comments

Comments
 (0)
0