Skip to content

Commit a57fa8b

Browse files
MariattaMariatta
authored
Add Git Bootcamp page (#144)
Provide a list of useful Git commands that are relevant to CPython's workflow, such as: - forking and cloning the repo - branching - committing - backporting - creating pull requests
1 parent 58d0e4c commit a57fa8b

File tree

2 files changed

+253
-0
lines changed

2 files changed

+253
-0
lines changed

‎gitbootcamp.rst

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
.. highlight:: console
2+
3+
.. _gitbootcamp:
4+
5+
Git Bootcamp and Cheat Sheet
6+
============================
7+
8+
In this section, we'll go over some commonly used Git commands that are
9+
relevant to CPython's workflow.
10+
11+
.. contents::
12+
13+
14+
Forking CPython GitHub Repository
15+
---------------------------------
16+
17+
You'll only need to do this once.
18+
19+
1. Go to https://github.com/python/cpython.
20+
21+
2. Press ``Fork`` on the top right.
22+
23+
3. When asked where to fork the repository, choose to fork it to your username.
24+
25+
4. Your fork will be created at https://github.com/<username>/cpython.
26+
27+
28+
Cloning The Forked CPython Repository
29+
-------------------------------------
30+
31+
You'll only need to do this once. From your command line::
32+
33+
$ git clone [email protected]:<username>/cpython.git
34+
$ cd cpython
35+
$ git remote add upstream [email protected]:python/cpython.git
36+
37+
38+
Listing the Remote Repositories
39+
-------------------------------
40+
41+
To list the remote repositories that are configured, along with their urls::
42+
43+
$ git remote -v
44+
45+
46+
Creating and Switching Branches
47+
-------------------------------
48+
49+
.. note::
50+
Never commit directly to the ``master`` branch.
51+
52+
Create a new branch and switch to it::
53+
54+
# creates a new branch off master and switch to it
55+
$ git checkout -b <branch-name> master
56+
57+
This is equivalent to::
58+
59+
# create a new branch off 'master', without checking it out
60+
$ git branch <branch-name> master
61+
# check out the branch
62+
$ git checkout <branch-name>
63+
64+
To find out which branch you are in now::
65+
66+
$ git branch
67+
68+
The current branch will have an asterisk next to the branch name. Note, this
69+
will list all of your local branches.
70+
71+
To list all the branches, including the remote branches::
72+
73+
$ git branch -a
74+
75+
To switch to a different branch::
76+
77+
$ git checkout <another-branch-name>
78+
79+
80+
Delete Local Branch
81+
-------------------
82+
83+
To delete branch that you no longer need::
84+
85+
$ git branch -D <branch-name>
86+
87+
88+
Staging and Committing Files
89+
----------------------------
90+
91+
1. To show the current changes::
92+
93+
$ git status
94+
95+
2. To stage the files to be included in your commit::
96+
97+
$ git add path/to/file1 path/to/file2 path/to/file3
98+
99+
3. To commit the files that have been staged (done in step 2)::
100+
101+
$ git commit -m "bpo-XXXX: This is the commit message."
102+
103+
104+
Reverting Changes
105+
-----------------
106+
107+
To revert changes to a file that has not been committed yet::
108+
109+
$ git checkout path/to/file
110+
111+
If the change has been committed, and now you want to reset it to whatever
112+
the origin is at::
113+
114+
$ git reset --hard HEAD
115+
116+
117+
Stashing Changes
118+
----------------
119+
120+
To stash away changes that are not ready to be committed yet::
121+
122+
$ git stash
123+
124+
To re-apply last stashed change::
125+
126+
$ git stash pop
127+
128+
129+
Pushing Changes
130+
---------------
131+
132+
Once your changes are ready for a review or a pull request, you'll need to push
133+
them to the remote repository.
134+
135+
::
136+
137+
$ git checkout <branch-name>
138+
$ git push origin <branch-name>
139+
140+
141+
Creating a Pull Request
142+
-----------------------
143+
144+
1. Go to https://github.com/python/cpython.
145+
146+
2. Click ``compare across forks`` link.
147+
148+
3. Select the base fork: ``python/cpython`` and base branch: ``master``.
149+
150+
4. Select the head fork: ``<username>/cpython`` and base branch: the branch
151+
containing your changes.
152+
153+
5. Press ``Create Pull Request`` button.
154+
155+
156+
Syncing With Upstream
157+
---------------------
158+
159+
Scenario:
160+
161+
- You forked the CPython repository some time ago.
162+
- Time passes.
163+
- There have been new commits made in upstream CPython repository.
164+
- Your forked CPython repository is no longer up to date.
165+
- You now want to update your forked CPython repository to be the same as
166+
upstream.
167+
168+
Solution::
169+
170+
$ git checkout master
171+
$ git pull --rebase upstream master
172+
$ git push origin master
173+
174+
The `--rebase` is only needed if you have local changes to the branch.
175+
176+
Another scenario:
177+
178+
- You created ``some-branch`` some time ago.
179+
- Time passes.
180+
- You made some commits to ``some-branch``.
181+
- Meanwhile, there are recent changes from upstream CPython repository.
182+
- You want to incorporate the recent changes from upstream into ``some-branch``.
183+
184+
Solution::
185+
186+
$ git checkout some-branch
187+
$ git fetch upstream
188+
$ git rebase upstream/master
189+
190+
191+
Backporting Merged Changes
192+
--------------------------
193+
194+
A pull request may need to be backported into one of the maintenance branches
195+
after it has been accepted and merged into ``master``. It is usually indicated
196+
by the label ``needs backport to X.Y`` on the pull request itself.
197+
198+
Use the utility script `cherry_picker.py <https://github.com/python/core-workflow/tree/master/cherry_picker>`_
199+
from the `core-workflow <https://github.com/python/core-workflow>`_
200+
repository to backport the commit .
201+
202+
The core developer who merged the pull request is expected to do the backport.
203+
204+
205+
Downloading Other's Patches
206+
---------------------------
207+
208+
Scenario:
209+
210+
- A contributor made a pull request to CPython.
211+
- Before merging it, you want to be able to test their changes locally.
212+
213+
Set up the following git alias::
214+
215+
$ git config --global alias.pr '!sh -c "git fetch upstream pull/${1}/head:pr_${1} && git checkout pr_${1}" -'
216+
217+
The alias only needs to be done once. After the alias is set up, you can get a
218+
local copy of a pull request as follows::
219+
220+
$ git pr <pr_number>
221+
222+
223+
Accepting and Merging A Pull Request
224+
------------------------------------
225+
226+
Pull requests can be accepted and merged by a Python Core Developer.
227+
228+
1. At the bottom of the pull request page, click the ``Squash and merge``
229+
button.
230+
231+
2. Adjust and clean up the commit message. Replace the reference
232+
to GitHub PR #XXX into GH-XXX.
233+
234+
Example of good commit message::
235+
236+
bpo-12345: Improve the spam module (GH-777)
237+
238+
* Add method A to the spam module
239+
* Update the documentation of the spam module
240+
241+
Example of bad commit message::
242+
243+
bpo-12345: Improve the spam module (#777)
244+
245+
* Improve the spam module
246+
* merge from master
247+
* adjust code based on review comment
248+
* rebased
249+
250+
3. Press the ``Confirm squash and merge`` button.

‎index.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ contributing to Python:
7272
* :doc:`help`
7373
* PEPs_ (Python Enhancement Proposals)
7474
* :doc:`gitdevs`
75+
* :doc:`gitbootcamp`
7576

7677
.. _branchstatus:
7778

@@ -169,6 +170,7 @@ Guide for contributing to Python:
169170
* :doc:`buildbots`
170171
* :doc:`coverity`
171172
* :doc:`gitdevs`
173+
* :doc:`gitbootcamp`
172174

173175
It is **recommended** that the above documents be read in the order listed. You
174176
can stop where you feel comfortable and begin contributing immediately without
@@ -307,6 +309,7 @@ Full Table of Contents
307309
buildslave
308310
gitdevs
309311
motivations
312+
gitbootcamp
310313

311314

312315
.. _Buildbot status: https://www.python.org/dev/buildbot/

0 commit comments

Comments
 (0)