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