Commit | Line | Data |
---|---|---|
d7dd28b6 LB |
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 RGS |
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 LB |
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 LB |
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 LB |
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 LB |
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 YO |
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 NC |
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 | ||
d7dd28b6 LB |
75 | =head1 OVERVIEW OF THE REPOSITORY |
76 | ||
77 | Once you have changed into the repository directory, you can inspect it. | |
78 | ||
d7dd28b6 | 79 | |
39219fd3 YO |
80 | After a clone the repository will contain a single local branch, which |
81 | will be the current branch as well, as indicated by the asterix. | |
82 | ||
83 | % git branch | |
84 | * blead | |
85 | ||
d9847473 | 86 | Using the -a switch to branch will also show the remote tracking branches in the |
39219fd3 YO |
87 | repository: |
88 | ||
d9847473 | 89 | % git branch -a |
09081495 | 90 | * blead |
d7dd28b6 LB |
91 | origin/HEAD |
92 | origin/blead | |
93 | ... | |
94 | ||
39219fd3 | 95 | The branches that begin with "origin" correspond to the "git remote" that |
d9847473 RGS |
96 | you cloned from (which is named "origin"). Each branch on the remote will |
97 | be exactly tracked by theses branches. You should NEVER do work on these | |
98 | remote tracking branches. You only ever do work in a local branch. Local | |
99 | branches can be configured to automerge (on pull) from a designated remote | |
100 | tracking branch. This is the case with the default branch C<blead> which | |
101 | will be configured to merge from the remote tracking branch | |
102 | C<origin/blead>. | |
39219fd3 | 103 | |
d7dd28b6 LB |
104 | You can see recent commits: |
105 | ||
c2cf2042 | 106 | % git log |
d7dd28b6 | 107 | |
23f8d33e | 108 | And pull new changes from the repository, and update your local repository |
39219fd3 | 109 | (must be clean first) |
d7dd28b6 LB |
110 | |
111 | % git pull | |
09081495 | 112 | |
39219fd3 YO |
113 | Assuming we are on the branch C<blead> immediately after a pull, this command |
114 | would be more or less equivalent to: | |
115 | ||
116 | % git fetch | |
117 | % git merge origin/blead | |
118 | ||
119 | In fact if you want to update your local repository without touching your working | |
120 | directory you do: | |
121 | ||
122 | % git fetch | |
123 | ||
d9847473 RGS |
124 | And if you want to update your remote-tracking branches for all defined remotes |
125 | simultaneously you can do | |
39219fd3 YO |
126 | |
127 | % git remote update | |
128 | ||
129 | Neither of these last two commands will update your working directory, however | |
d9847473 | 130 | both will update the remote-tracking branches in your repository. |
39219fd3 | 131 | |
09081495 LB |
132 | To switch to another branch: |
133 | ||
134 | % git checkout origin/maint-5.8-dor | |
135 | ||
136 | To switch back to blead: | |
137 | ||
138 | % git checkout blead | |
c2cf2042 | 139 | |
39219fd3 YO |
140 | =head2 FINDING OUT YOUR STATUS |
141 | ||
142 | The most common git command you will use will probably be | |
143 | ||
144 | % git status | |
145 | ||
23f8d33e | 146 | This command will produce as output a description of the current state of the |
39219fd3 | 147 | repository, including modified files and unignored untracked files, and in addition |
23f8d33e YO |
148 | it will show things like what files have been staged for the next commit, |
149 | and usually some useful information about how to change things. For instance the | |
39219fd3 YO |
150 | following: |
151 | ||
152 | $ git status | |
153 | # On branch blead | |
154 | # Your branch is ahead of 'origin/blead' by 1 commit. | |
155 | # | |
156 | # Changes to be committed: | |
157 | # (use "git reset HEAD <file>..." to unstage) | |
158 | # | |
159 | # modified: pod/perlrepository.pod | |
160 | # | |
161 | # Changed but not updated: | |
162 | # (use "git add <file>..." to update what will be committed) | |
163 | # | |
164 | # modified: pod/perlrepository.pod | |
165 | # | |
166 | # Untracked files: | |
167 | # (use "git add <file>..." to include in what will be committed) | |
168 | # | |
169 | # deliberate.untracked | |
170 | ||
171 | This shows that there were changes to this document staged for commit, and | |
172 | that there were further changes in the working directory not yet staged. It | |
173 | also shows that there was an untracked file in the working directory, and as | |
174 | you can see shows how to change all of this. It also shows that there | |
175 | is one commit on the working branch C<blead> which has not been pushed to the | |
23f8d33e | 176 | C<origin> remote yet. B<NOTE>: that this output is also what you see as a |
d9847473 | 177 | template if you do not provide a message to C<git commit>. |
7f6effc7 YO |
178 | |
179 | Assuming we commit all the mentioned changes above: | |
180 | ||
181 | % git commit -a -m'explain git status and stuff about remotes' | |
182 | Created commit daf8e63: explain git status and stuff about remotes | |
183 | 1 files changed, 83 insertions(+), 3 deletions(-) | |
184 | ||
185 | We can re-run git status and see something like this: | |
186 | ||
187 | % git status | |
188 | # On branch blead | |
189 | # Your branch is ahead of 'origin/blead' by 2 commits. | |
190 | # | |
191 | # Untracked files: | |
192 | # (use "git add <file>..." to include in what will be committed) | |
193 | # | |
194 | # deliberate.untracked | |
195 | nothing added to commit but untracked files present (use "git add" to track) | |
196 | ||
39219fd3 | 197 | |
23f8d33e | 198 | When in doubt, before you do anything else, check your status and read it |
39219fd3 YO |
199 | carefully, many questions are answered directly by the git status output. |
200 | ||
c2cf2042 LB |
201 | =head1 SUBMITTING A PATCH |
202 | ||
203 | If you have a patch in mind for Perl, you should first get a copy of | |
204 | the repository: | |
205 | ||
206 | % git clone git://perl5.git.perl.org/perl.git perl-git | |
207 | ||
208 | Then change into the directory: | |
209 | ||
210 | % cd perl-git | |
211 | ||
12322d22 | 212 | Alternatively, if you already have a Perl repository, you should |
f5445761 | 213 | ensure that you're on the I<blead> branch, and your repository |
12322d22 A |
214 | is up to date: |
215 | ||
216 | % git checkout blead | |
217 | % git pull | |
218 | ||
219 | Now that we have everything up to date, we need to create a temporary new | |
220 | branch for these changes and switch into it: | |
b1fccde5 | 221 | |
a9b05323 | 222 | % git checkout -b orange |
23f8d33e | 223 | |
a9b05323 YO |
224 | which is the short form of |
225 | ||
b1fccde5 LB |
226 | % git branch orange |
227 | % git checkout orange | |
228 | ||
c2cf2042 LB |
229 | Then make your changes. For example, if Leon Brocard changes his name |
230 | to Orange Brocard, we should change his name in the AUTHORS file: | |
231 | ||
232 | % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS | |
233 | ||
234 | You can see what files are changed: | |
235 | ||
236 | % git status | |
237 | # On branch blead | |
238 | # Changes to be committed: | |
239 | # (use "git reset HEAD <file>..." to unstage) | |
240 | # | |
241 | # modified: AUTHORS | |
242 | # | |
243 | ||
c2cf2042 LB |
244 | And you can see the changes: |
245 | ||
246 | % git diff | |
247 | diff --git a/AUTHORS b/AUTHORS | |
248 | index 293dd70..722c93e 100644 | |
249 | --- a/AUTHORS | |
250 | +++ b/AUTHORS | |
7df2e4bc | 251 | @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie> |
c2cf2042 LB |
252 | Laszlo Molnar <laszlo.molnar@eth.ericsson.se> |
253 | Leif Huhn <leif@hale.dkstat.com> | |
254 | Len Johnson <lenjay@ibm.net> | |
255 | -Leon Brocard <acme@astray.com> | |
256 | +Orange Brocard <acme@astray.com> | |
257 | Les Peters <lpeters@aol.net> | |
258 | Lesley Binks <lesley.binks@gmail.com> | |
259 | Lincoln D. Stein <lstein@cshl.org> | |
260 | ||
261 | Now commit your change locally: | |
262 | ||
263 | % git add AUTHORS | |
264 | % git commit -m 'Rename Leon Brocard to Orange Brocard' | |
265 | Created commit 6196c1d: Rename Leon Brocard to Orange Brocard | |
266 | 1 files changed, 1 insertions(+), 1 deletions(-) | |
267 | ||
268 | Now you should create a patch file for all your local changes: | |
269 | ||
2af192ee | 270 | % git format-patch origin |
c2cf2042 LB |
271 | 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch |
272 | ||
273 | You should now send an email to perl5-porters@perl.org with a | |
274 | description of your changes, and attach this patch file as an | |
275 | attachment. | |
276 | ||
b1fccde5 LB |
277 | If you want to delete your temporary branch, you may do so with: |
278 | ||
279 | % git checkout blead | |
280 | % git branch -d orange | |
281 | error: The branch 'orange' is not an ancestor of your current HEAD. | |
282 | If you are sure you want to delete it, run 'git branch -D orange'. | |
283 | % git branch -D orange | |
284 | Deleted branch orange. | |
7df2e4bc LB |
285 | |
286 | =head1 ACCEPTING A PATCH | |
287 | ||
288 | If you have received a patch file generated using the above section, | |
289 | you should try out the patch. | |
290 | ||
291 | First we need to create a temporary new branch for these changes and | |
292 | switch into it: | |
293 | ||
a9b05323 | 294 | % git checkout -b experimental |
7df2e4bc LB |
295 | |
296 | Now we should apply the patch: | |
297 | ||
2af192ee | 298 | % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch |
7df2e4bc LB |
299 | Applying Rename Leon Brocard to Orange Brocard |
300 | ||
301 | Now we can inspect the change: | |
302 | ||
303 | % git log | |
304 | commit b1b3dab48344cff6de4087efca3dbd63548ab5e2 | |
305 | Author: Leon Brocard <acme@astray.com> | |
306 | Date: Fri Dec 19 17:02:59 2008 +0000 | |
307 | ||
308 | Rename Leon Brocard to Orange Brocard | |
309 | ... | |
310 | ||
311 | % git diff blead | |
312 | diff --git a/AUTHORS b/AUTHORS | |
313 | index 293dd70..722c93e 100644 | |
314 | --- a/AUTHORS | |
315 | +++ b/AUTHORS | |
316 | @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie> | |
317 | Laszlo Molnar <laszlo.molnar@eth.ericsson.se> | |
318 | Leif Huhn <leif@hale.dkstat.com> | |
319 | Len Johnson <lenjay@ibm.net> | |
320 | -Leon Brocard <acme@astray.com> | |
321 | +Orange Brocard <acme@astray.com> | |
322 | Les Peters <lpeters@aol.net> | |
323 | Lesley Binks <lesley.binks@gmail.com> | |
324 | Lincoln D. Stein <lstein@cshl.org> | |
325 | ||
326 | If you are a committer to Perl and you think the patch is good, you can | |
75fb7651 | 327 | then merge it into blead then push it out to the main repository: |
7df2e4bc LB |
328 | |
329 | % git checkout blead | |
d9847473 | 330 | % git merge experimental |
75fb7651 | 331 | % git push |
7df2e4bc LB |
332 | |
333 | If you want to delete your temporary branch, you may do so with: | |
334 | ||
335 | % git checkout blead | |
336 | % git branch -d experimental | |
337 | error: The branch 'experimental' is not an ancestor of your current HEAD. | |
338 | If you are sure you want to delete it, run 'git branch -D experimental'. | |
339 | % git branch -D experimental | |
340 | Deleted branch experimental. |