Commit | Line | Data |
d7dd28b6 |
1 | =head1 NAME |
2 | |
3 | perlrepository - Using the Perl source repository |
4 | |
5 | =head1 SYNOPSIS |
6 | |
7 | All of Perl's source code is kept centrally in a Git repository. The |
8 | repository contains many Perl revisions from Perl 1 onwards and all |
9 | the revisions from Perforce, the version control system we were using |
10 | previously. This repository is accessible in different ways. |
11 | |
12 | The full repository takes up about 80MB of disk space. A check out of |
d9847473 |
13 | the blead branch (that is, the master branch, which contains bleadperl, |
14 | the development version of perl 5) takes up about 160MB of disk space |
15 | (including the repository). A build of bleadperl takes up about 200MB |
16 | (including the repository and the check out). |
d7dd28b6 |
17 | |
18 | =head1 GETTING ACCESS TO THE REPOSITORY |
19 | |
20 | =head2 READ ACCESS VIA THE WEB |
21 | |
22 | You may access this over the web. This allows you to browse the tree, |
23 | see recent commits, search for particular commits and more. You may |
24 | access it at: |
25 | |
26 | http://perl5.git.perl.org/perl.git |
27 | |
28 | =head2 READ ACCESS VIA GIT |
29 | |
30 | You will need a copy of Git for your computer. You can fetch a copy of |
31 | the repository using the Git protocol (which uses port 9418): |
32 | |
3b8a5fb0 |
33 | git clone git://perl5.git.perl.org/perl.git perl-git |
d7dd28b6 |
34 | |
3b8a5fb0 |
35 | This clones the repository and makes a local copy in the 'perl-git' |
d7dd28b6 |
36 | directory. |
37 | |
38 | If your local network does not allow you to use port 9418, then you can |
572f57ba |
39 | fetch a copy of the repository over HTTP (this is slower): |
d7dd28b6 |
40 | |
3b8a5fb0 |
41 | git clone http://perl5.git.perl.org/perl.git perl-http |
d7dd28b6 |
42 | |
3b8a5fb0 |
43 | This clones the repository and makes a local copy in the 'perl-http' |
d7dd28b6 |
44 | directory. |
45 | |
46 | =head2 WRITE ACCESS TO THE REPOSITORY |
47 | |
48 | If you are a committer, then you can fetch a copy of the repository that |
49 | you can push back on with: |
50 | |
3b8a5fb0 |
51 | git clone ssh://perl5.git.perl.org/gitroot/perl.git perl-ssh |
d7dd28b6 |
52 | |
3b8a5fb0 |
53 | This clones the repository and makes a local copy in the 'perl-ssh' |
d7dd28b6 |
54 | directory. |
55 | |
1a0f15d5 |
56 | If you clone using git, which is faster than ssh, then you will need to |
d9847473 |
57 | modify your config in order to enable pushing. Edit F<.git/config> where |
1a0f15d5 |
58 | you will see something like: |
59 | |
60 | [remote "origin"] |
61 | url = git://perl5.git.perl.org/perl.git |
62 | |
63 | change that to something like this: |
64 | |
65 | [remote "origin"] |
66 | url = ssh://perl5.git.perl.org/gitroot/perl.git |
67 | |
68 | NOTE: there are symlinks set up so that the /gitroot is actually optional. |
d7dd28b6 |
69 | |
184487f0 |
70 | You can also set up your user name and e-mail address. For example |
71 | |
72 | % git config user.name "Leon Brocard" |
73 | % git config user.email acme@astray.com |
74 | |
f6c12373 |
75 | It is also possible to keep C<origin> as a git remote, and add a new remote for ssh access: |
76 | |
77 | % git remote add camel user@camel:/gitroot/perl.git |
78 | |
79 | This allows you to update your local repository by pulling from C<origin>, which is faster and doesn't require you to authentify, and to push your changes back with the C<camel> remote: |
80 | |
81 | % git fetch camel |
82 | % git push camel |
83 | |
84 | The C<fetch> command just updates the C<camel> refs, as the objects themselves should have been fetched when pulling from C<origin>. |
85 | |
d7dd28b6 |
86 | =head1 OVERVIEW OF THE REPOSITORY |
87 | |
88 | Once you have changed into the repository directory, you can inspect it. |
89 | |
d7dd28b6 |
90 | |
39219fd3 |
91 | After a clone the repository will contain a single local branch, which |
92 | will be the current branch as well, as indicated by the asterix. |
93 | |
94 | % git branch |
95 | * blead |
96 | |
d9847473 |
97 | Using the -a switch to branch will also show the remote tracking branches in the |
39219fd3 |
98 | repository: |
99 | |
d9847473 |
100 | % git branch -a |
09081495 |
101 | * blead |
d7dd28b6 |
102 | origin/HEAD |
103 | origin/blead |
104 | ... |
105 | |
39219fd3 |
106 | The branches that begin with "origin" correspond to the "git remote" that |
d9847473 |
107 | you cloned from (which is named "origin"). Each branch on the remote will |
108 | be exactly tracked by theses branches. You should NEVER do work on these |
109 | remote tracking branches. You only ever do work in a local branch. Local |
110 | branches can be configured to automerge (on pull) from a designated remote |
111 | tracking branch. This is the case with the default branch C<blead> which |
112 | will be configured to merge from the remote tracking branch |
113 | C<origin/blead>. |
39219fd3 |
114 | |
d7dd28b6 |
115 | You can see recent commits: |
116 | |
c2cf2042 |
117 | % git log |
d7dd28b6 |
118 | |
23f8d33e |
119 | And pull new changes from the repository, and update your local repository |
39219fd3 |
120 | (must be clean first) |
d7dd28b6 |
121 | |
122 | % git pull |
09081495 |
123 | |
39219fd3 |
124 | Assuming we are on the branch C<blead> immediately after a pull, this command |
125 | would be more or less equivalent to: |
126 | |
127 | % git fetch |
128 | % git merge origin/blead |
129 | |
130 | In fact if you want to update your local repository without touching your working |
131 | directory you do: |
132 | |
133 | % git fetch |
134 | |
d9847473 |
135 | And if you want to update your remote-tracking branches for all defined remotes |
136 | simultaneously you can do |
39219fd3 |
137 | |
138 | % git remote update |
139 | |
140 | Neither of these last two commands will update your working directory, however |
d9847473 |
141 | both will update the remote-tracking branches in your repository. |
39219fd3 |
142 | |
09081495 |
143 | To switch to another branch: |
144 | |
145 | % git checkout origin/maint-5.8-dor |
146 | |
147 | To switch back to blead: |
148 | |
149 | % git checkout blead |
c2cf2042 |
150 | |
39219fd3 |
151 | =head2 FINDING OUT YOUR STATUS |
152 | |
153 | The most common git command you will use will probably be |
154 | |
155 | % git status |
156 | |
23f8d33e |
157 | This command will produce as output a description of the current state of the |
39219fd3 |
158 | repository, including modified files and unignored untracked files, and in addition |
23f8d33e |
159 | it will show things like what files have been staged for the next commit, |
160 | and usually some useful information about how to change things. For instance the |
39219fd3 |
161 | following: |
162 | |
163 | $ git status |
164 | # On branch blead |
165 | # Your branch is ahead of 'origin/blead' by 1 commit. |
166 | # |
167 | # Changes to be committed: |
168 | # (use "git reset HEAD <file>..." to unstage) |
169 | # |
170 | # modified: pod/perlrepository.pod |
171 | # |
172 | # Changed but not updated: |
173 | # (use "git add <file>..." to update what will be committed) |
174 | # |
175 | # modified: pod/perlrepository.pod |
176 | # |
177 | # Untracked files: |
178 | # (use "git add <file>..." to include in what will be committed) |
179 | # |
180 | # deliberate.untracked |
181 | |
182 | This shows that there were changes to this document staged for commit, and |
183 | that there were further changes in the working directory not yet staged. It |
184 | also shows that there was an untracked file in the working directory, and as |
185 | you can see shows how to change all of this. It also shows that there |
186 | is one commit on the working branch C<blead> which has not been pushed to the |
23f8d33e |
187 | C<origin> remote yet. B<NOTE>: that this output is also what you see as a |
d9847473 |
188 | template if you do not provide a message to C<git commit>. |
7f6effc7 |
189 | |
190 | Assuming we commit all the mentioned changes above: |
191 | |
192 | % git commit -a -m'explain git status and stuff about remotes' |
193 | Created commit daf8e63: explain git status and stuff about remotes |
194 | 1 files changed, 83 insertions(+), 3 deletions(-) |
195 | |
196 | We can re-run git status and see something like this: |
197 | |
198 | % git status |
199 | # On branch blead |
200 | # Your branch is ahead of 'origin/blead' by 2 commits. |
201 | # |
202 | # Untracked files: |
203 | # (use "git add <file>..." to include in what will be committed) |
204 | # |
205 | # deliberate.untracked |
206 | nothing added to commit but untracked files present (use "git add" to track) |
207 | |
39219fd3 |
208 | |
23f8d33e |
209 | When in doubt, before you do anything else, check your status and read it |
39219fd3 |
210 | carefully, many questions are answered directly by the git status output. |
211 | |
c2cf2042 |
212 | =head1 SUBMITTING A PATCH |
213 | |
214 | If you have a patch in mind for Perl, you should first get a copy of |
215 | the repository: |
216 | |
217 | % git clone git://perl5.git.perl.org/perl.git perl-git |
218 | |
219 | Then change into the directory: |
220 | |
221 | % cd perl-git |
222 | |
12322d22 |
223 | Alternatively, if you already have a Perl repository, you should |
f5445761 |
224 | ensure that you're on the I<blead> branch, and your repository |
12322d22 |
225 | is up to date: |
226 | |
227 | % git checkout blead |
228 | % git pull |
229 | |
230 | Now that we have everything up to date, we need to create a temporary new |
231 | branch for these changes and switch into it: |
b1fccde5 |
232 | |
a9b05323 |
233 | % git checkout -b orange |
23f8d33e |
234 | |
a9b05323 |
235 | which is the short form of |
236 | |
b1fccde5 |
237 | % git branch orange |
238 | % git checkout orange |
239 | |
c2cf2042 |
240 | Then make your changes. For example, if Leon Brocard changes his name |
241 | to Orange Brocard, we should change his name in the AUTHORS file: |
242 | |
243 | % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS |
244 | |
245 | You can see what files are changed: |
246 | |
247 | % git status |
248 | # On branch blead |
249 | # Changes to be committed: |
250 | # (use "git reset HEAD <file>..." to unstage) |
251 | # |
252 | # modified: AUTHORS |
253 | # |
254 | |
c2cf2042 |
255 | And you can see the changes: |
256 | |
257 | % git diff |
258 | diff --git a/AUTHORS b/AUTHORS |
259 | index 293dd70..722c93e 100644 |
260 | --- a/AUTHORS |
261 | +++ b/AUTHORS |
7df2e4bc |
262 | @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie> |
c2cf2042 |
263 | Laszlo Molnar <laszlo.molnar@eth.ericsson.se> |
264 | Leif Huhn <leif@hale.dkstat.com> |
265 | Len Johnson <lenjay@ibm.net> |
266 | -Leon Brocard <acme@astray.com> |
267 | +Orange Brocard <acme@astray.com> |
268 | Les Peters <lpeters@aol.net> |
269 | Lesley Binks <lesley.binks@gmail.com> |
270 | Lincoln D. Stein <lstein@cshl.org> |
271 | |
272 | Now commit your change locally: |
273 | |
274 | % git add AUTHORS |
275 | % git commit -m 'Rename Leon Brocard to Orange Brocard' |
276 | Created commit 6196c1d: Rename Leon Brocard to Orange Brocard |
277 | 1 files changed, 1 insertions(+), 1 deletions(-) |
278 | |
279 | Now you should create a patch file for all your local changes: |
280 | |
2af192ee |
281 | % git format-patch origin |
c2cf2042 |
282 | 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch |
283 | |
284 | You should now send an email to perl5-porters@perl.org with a |
285 | description of your changes, and attach this patch file as an |
286 | attachment. |
287 | |
b1fccde5 |
288 | If you want to delete your temporary branch, you may do so with: |
289 | |
290 | % git checkout blead |
291 | % git branch -d orange |
292 | error: The branch 'orange' is not an ancestor of your current HEAD. |
293 | If you are sure you want to delete it, run 'git branch -D orange'. |
294 | % git branch -D orange |
295 | Deleted branch orange. |
7df2e4bc |
296 | |
297 | =head1 ACCEPTING A PATCH |
298 | |
299 | If you have received a patch file generated using the above section, |
300 | you should try out the patch. |
301 | |
302 | First we need to create a temporary new branch for these changes and |
303 | switch into it: |
304 | |
a9b05323 |
305 | % git checkout -b experimental |
7df2e4bc |
306 | |
09645c26 |
307 | Patches that were formatted by C<git format-patch> are applied with C<git am>: |
7df2e4bc |
308 | |
2af192ee |
309 | % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch |
7df2e4bc |
310 | Applying Rename Leon Brocard to Orange Brocard |
311 | |
09645c26 |
312 | If just a raw diff is provided, it is also possible use this two-step process: |
313 | |
314 | % git apply bugfix.diff |
315 | % git commit -am "Some fixing" --author="That Guy <that.guy@internets.com>" |
316 | |
7df2e4bc |
317 | Now we can inspect the change: |
318 | |
319 | % git log |
320 | commit b1b3dab48344cff6de4087efca3dbd63548ab5e2 |
321 | Author: Leon Brocard <acme@astray.com> |
322 | Date: Fri Dec 19 17:02:59 2008 +0000 |
323 | |
324 | Rename Leon Brocard to Orange Brocard |
325 | ... |
326 | |
327 | % git diff blead |
328 | diff --git a/AUTHORS b/AUTHORS |
329 | index 293dd70..722c93e 100644 |
330 | --- a/AUTHORS |
331 | +++ b/AUTHORS |
332 | @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie> |
333 | Laszlo Molnar <laszlo.molnar@eth.ericsson.se> |
334 | Leif Huhn <leif@hale.dkstat.com> |
335 | Len Johnson <lenjay@ibm.net> |
336 | -Leon Brocard <acme@astray.com> |
337 | +Orange Brocard <acme@astray.com> |
338 | Les Peters <lpeters@aol.net> |
339 | Lesley Binks <lesley.binks@gmail.com> |
340 | Lincoln D. Stein <lstein@cshl.org> |
341 | |
342 | If you are a committer to Perl and you think the patch is good, you can |
75fb7651 |
343 | then merge it into blead then push it out to the main repository: |
7df2e4bc |
344 | |
345 | % git checkout blead |
d9847473 |
346 | % git merge experimental |
75fb7651 |
347 | % git push |
7df2e4bc |
348 | |
349 | If you want to delete your temporary branch, you may do so with: |
350 | |
351 | % git checkout blead |
352 | % git branch -d experimental |
353 | error: The branch 'experimental' is not an ancestor of your current HEAD. |
354 | If you are sure you want to delete it, run 'git branch -D experimental'. |
355 | % git branch -D experimental |
356 | Deleted branch experimental. |
b0d36535 |
357 | |
358 | =head1 CLEANING A WORKING DIRECTORY |
359 | |
360 | The command C<git clean> can with varying arguments be used as a replacement for make-clean. |
361 | |
362 | To reset your working directory to a pristine condition you can do: |
363 | |
364 | git clean -dxf |
365 | |
366 | However, be aware this will delete ALL untracked content. You can use |
367 | |
368 | git clean -Xf |
369 | |
370 | to remove all ignored untracked files, such as build and test byproduct, but leave any |
371 | manually created files alone. |
372 | |
d82a90c1 |
373 | =head1 BISECTING |
374 | |
375 | C<git> provides a built-in way to determine, with a binary search in the history, which commit should be blamed for introducing a given bug. |
376 | |
377 | Suppose that we have a script F<~/testcase.pl> that exits with C<0> when some behaviour is correct, and with C<1> when it's faulty. We need an helper script that automates building C<perl> and running the testcase: |
378 | |
379 | % cat ~/run |
380 | #!/bin/sh |
381 | git clean -dxf |
382 | # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line |
383 | sh Configure -des -Dusedevel -Doptimize="-g" || exit 125 |
384 | make || exit 125 |
385 | ./perl -Ilib ~/testcase.pl |
386 | |
387 | This script may return C<125> to indicate that the corresponding commit should be skipped. Otherwise, it returns the status of F<~/testcase.pl>. |
388 | |
389 | We first enter in bisect mode with: |
390 | |
391 | % git bisect start |
392 | |
393 | For example, if the bug is present on C<HEAD> but wasn't in 5.10.0, C<git> will learn about this when you enter: |
394 | |
395 | % git bisect bad |
396 | % git bisect good perl-5.10.0 |
397 | Bisecting: 853 revisions left to test after this |
398 | |
399 | This results in checking out the median commit between C<HEAD> and C<perl-5.10.0>. We can then run the bisecting process with: |
400 | |
401 | % git bisect run ~/run |
402 | |
403 | When the first bad commit is isolated, C<git bisect> will tell you so: |
404 | |
405 | ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit |
406 | commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 |
407 | Author: Dave Mitchell <davem@fdisolutions.com> |
408 | Date: Sat Feb 9 14:56:23 2008 +0000 |
409 | |
410 | [perl #49472] Attributes + Unkown Error |
411 | ... |
412 | |
413 | bisect run success |
414 | |
415 | You can peek into the bisecting process with C<git bisect log> and C<git bisect visualize>. C<git bisect reset> will get you out of bisect mode. |
416 | |
417 | Please note that the first C<good> state must be an ancestor of the first C<bad> state. If you want to search for the commit that I<solved> some bug, you have to negate your test case (i.e. exit with C<1> if OK and C<0> if not) and still mark the lower bound as C<good> and the upper as C<bad>. The "first bad commit" has then to be understood as the "first commit where the bug is solved". |
418 | |
419 | C<git help bisect> has much more information on how you can tweak your binary searches. |
9d68b7ed |
420 | |
421 | =head1 COMITTING TO MAINTENANCE VERSIONS |
422 | |
423 | To commit to a maintenance version of perl, you need to create a local |
424 | tracking branch: |
425 | |
426 | % git checkout --track -b maint-5.005 origin/maint-5.005 |
427 | |
428 | This creates a local branch named maint-5.005, which tracks the remote |
429 | branch origin/maint-5.005. Then you can pull, commit, merge and push |
430 | as before. |