This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
In the patch section, show how to work on a temporary branch
[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
b1fccde5
LB
108First we need to create a temporary new branch for these changes and
109switch into it:
110
111 % git branch orange
112 % git checkout orange
113
c2cf2042
LB
114Then make your changes. For example, if Leon Brocard changes his name
115to Orange Brocard, we should change his name in the AUTHORS file:
116
117 % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
118
119You can see what files are changed:
120
121 % git status
122 # On branch blead
123 # Changes to be committed:
124 # (use "git reset HEAD <file>..." to unstage)
125 #
126 # modified: AUTHORS
127 #
128
129
130And you can see the changes:
131
132 % git diff
133 diff --git a/AUTHORS b/AUTHORS
134 index 293dd70..722c93e 100644
135 --- a/AUTHORS
136 +++ b/AUTHORS
137 @@ -541,7 +541,7 @@
138 Lars Hecking <lhecking@nmrc.ucc.ie>
139 Laszlo Molnar <laszlo.molnar@eth.ericsson.se>
140 Leif Huhn <leif@hale.dkstat.com>
141 Len Johnson <lenjay@ibm.net>
142 -Leon Brocard <acme@astray.com>
143 +Orange Brocard <acme@astray.com>
144 Les Peters <lpeters@aol.net>
145 Lesley Binks <lesley.binks@gmail.com>
146 Lincoln D. Stein <lstein@cshl.org>
147
148Now commit your change locally:
149
150 % git add AUTHORS
151 % git commit -m 'Rename Leon Brocard to Orange Brocard'
152 Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
153 1 files changed, 1 insertions(+), 1 deletions(-)
154
155Now you should create a patch file for all your local changes:
156
157 % git-format-patch origin
158 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
159
160You should now send an email to perl5-porters@perl.org with a
161description of your changes, and attach this patch file as an
162attachment.
163
b1fccde5
LB
164If you want to delete your temporary branch, you may do so with:
165
166 % git checkout blead
167 % git branch -d orange
168 error: The branch 'orange' is not an ancestor of your current HEAD.
169 If you are sure you want to delete it, run 'git branch -D orange'.
170 % git branch -D orange
171 Deleted branch orange.