This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
use checkout -b and not the more verbose two step process
[perl5.git] / pod / perlrepository.pod
CommitLineData
d7dd28b6
LB
1=head1 NAME
2
3perlrepository - Using the Perl source repository
4
5=head1 SYNOPSIS
6
7All of Perl's source code is kept centrally in a Git repository. The
8repository contains many Perl revisions from Perl 1 onwards and all
9the revisions from Perforce, the version control system we were using
10previously. This repository is accessible in different ways.
11
12The full repository takes up about 80MB of disk space. A check out of
13blead takes up about 160MB of disk space (including the repository). A
14build of blead takes up about 200MB (including the repository and the
15check out).
16
17=head1 GETTING ACCESS TO THE REPOSITORY
18
19=head2 READ ACCESS VIA THE WEB
20
21You may access this over the web. This allows you to browse the tree,
22see recent commits, search for particular commits and more. You may
23access it at:
24
25 http://perl5.git.perl.org/perl.git
26
27=head2 READ ACCESS VIA GIT
28
29You will need a copy of Git for your computer. You can fetch a copy of
30the 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 34This clones the repository and makes a local copy in the 'perl-git'
d7dd28b6
LB
35directory.
36
37If your local network does not allow you to use port 9418, then you can
572f57ba 38fetch 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 42This clones the repository and makes a local copy in the 'perl-http'
d7dd28b6
LB
43directory.
44
45=head2 WRITE ACCESS TO THE REPOSITORY
46
47If you are a committer, then you can fetch a copy of the repository that
48you can push back on with:
49
3b8a5fb0 50 git clone ssh://perl5.git.perl.org/gitroot/perl.git perl-ssh
d7dd28b6 51
3b8a5fb0 52This clones the repository and makes a local copy in the 'perl-ssh'
d7dd28b6
LB
53directory.
54
1a0f15d5 55If you clone using git, which is faster than ssh, then you will need to
c2cf2042 56modify your config in order to enable pushing. Edit .git/config where
1a0f15d5
YO
57you will see something like:
58
59 [remote "origin"]
60 url = git://perl5.git.perl.org/perl.git
61
62change that to something like this:
63
64 [remote "origin"]
65 url = ssh://perl5.git.perl.org/gitroot/perl.git
66
67NOTE: there are symlinks set up so that the /gitroot is actually optional.
d7dd28b6
LB
68
69=head1 OVERVIEW OF THE REPOSITORY
70
71Once you have changed into the repository directory, you can inspect it.
72
73The repository contains a few branches:
74
09081495
LB
75 % git branch -a
76 * blead
d7dd28b6
LB
77 origin/HEAD
78 origin/blead
79 ...
80
81You can see recent commits:
82
c2cf2042 83 % git log
d7dd28b6
LB
84
85And pull new changes from the repository:
86
87 % git pull
09081495
LB
88
89To switch to another branch:
90
91 % git checkout origin/maint-5.8-dor
92
93To switch back to blead:
94
95 % git checkout blead
c2cf2042
LB
96
97=head1 SUBMITTING A PATCH
98
99If you have a patch in mind for Perl, you should first get a copy of
100the repository:
101
102 % git clone git://perl5.git.perl.org/perl.git perl-git
103
104Then change into the directory:
105
106 % cd perl-git
107
12322d22 108Alternatively, if you already have a Perl repository, you should
f5445761 109ensure that you're on the I<blead> branch, and your repository
12322d22
A
110is up to date:
111
112 % git checkout blead
113 % git pull
114
115Now that we have everything up to date, we need to create a temporary new
116branch for these changes and switch into it:
b1fccde5 117
a9b05323
YO
118 % git checkout -b orange
119
120which is the short form of
121
b1fccde5
LB
122 % git branch orange
123 % git checkout orange
124
c2cf2042
LB
125Then make your changes. For example, if Leon Brocard changes his name
126to Orange Brocard, we should change his name in the AUTHORS file:
127
128 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
129
130You can see what files are changed:
131
132 % git status
133 # On branch blead
134 # Changes to be committed:
135 # (use "git reset HEAD <file>..." to unstage)
136 #
137 # modified: AUTHORS
138 #
139
c2cf2042
LB
140And you can see the changes:
141
142 % git diff
143 diff --git a/AUTHORS b/AUTHORS
144 index 293dd70..722c93e 100644
145 --- a/AUTHORS
146 +++ b/AUTHORS
7df2e4bc 147 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
c2cf2042
LB
148 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
149 Leif Huhn <leif@hale.dkstat.com>
150 Len Johnson <lenjay@ibm.net>
151 -Leon Brocard <acme@astray.com>
152 +Orange Brocard <acme@astray.com>
153 Les Peters <lpeters@aol.net>
154 Lesley Binks <lesley.binks@gmail.com>
155 Lincoln D. Stein <lstein@cshl.org>
156
157Now commit your change locally:
158
159 % git add AUTHORS
160 % git commit -m 'Rename Leon Brocard to Orange Brocard'
161 Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
162 1 files changed, 1 insertions(+), 1 deletions(-)
163
164Now you should create a patch file for all your local changes:
165
2af192ee 166 % git format-patch origin
c2cf2042
LB
167 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
168
169You should now send an email to perl5-porters@perl.org with a
170description of your changes, and attach this patch file as an
171attachment.
172
b1fccde5
LB
173If you want to delete your temporary branch, you may do so with:
174
175 % git checkout blead
176 % git branch -d orange
177 error: The branch 'orange' is not an ancestor of your current HEAD.
178 If you are sure you want to delete it, run 'git branch -D orange'.
179 % git branch -D orange
180 Deleted branch orange.
7df2e4bc
LB
181
182=head1 ACCEPTING A PATCH
183
184If you have received a patch file generated using the above section,
185you should try out the patch.
186
187First we need to create a temporary new branch for these changes and
188switch into it:
189
a9b05323 190 % git checkout -b experimental
7df2e4bc
LB
191
192Now we should apply the patch:
193
2af192ee 194 % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
7df2e4bc
LB
195 Applying Rename Leon Brocard to Orange Brocard
196
197Now we can inspect the change:
198
199 % git log
200 commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
201 Author: Leon Brocard <acme@astray.com>
202 Date: Fri Dec 19 17:02:59 2008 +0000
203
204 Rename Leon Brocard to Orange Brocard
205 ...
206
207 % git diff blead
208 diff --git a/AUTHORS b/AUTHORS
209 index 293dd70..722c93e 100644
210 --- a/AUTHORS
211 +++ b/AUTHORS
212 @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie>
213 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
214 Leif Huhn <leif@hale.dkstat.com>
215 Len Johnson <lenjay@ibm.net>
216 -Leon Brocard <acme@astray.com>
217 +Orange Brocard <acme@astray.com>
218 Les Peters <lpeters@aol.net>
219 Lesley Binks <lesley.binks@gmail.com>
220 Lincoln D. Stein <lstein@cshl.org>
221
222If you are a committer to Perl and you think the patch is good, you can
75fb7651 223then merge it into blead then push it out to the main repository:
7df2e4bc
LB
224
225 % git checkout blead
226 % git pull . experimental
75fb7651 227 % git push
7df2e4bc
LB
228
229If you want to delete your temporary branch, you may do so with:
230
231 % git checkout blead
232 % git branch -d experimental
233 error: The branch 'experimental' is not an ancestor of your current HEAD.
234 If you are sure you want to delete it, run 'git branch -D experimental'.
235 % git branch -D experimental
236 Deleted branch experimental.