| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "PERLGIT 1" |
| 58 |
.TH PERLGIT 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
perlgit \- Detailed information about git and the Perl repository |
| 65 |
.SH DESCRIPTION |
| 66 |
.IX Header "DESCRIPTION" |
| 67 |
This document provides details on using git to develop Perl. If you are |
| 68 |
just interested in working on a quick patch, see perlhack first. |
| 69 |
This document is intended for people who are regular contributors to |
| 70 |
Perl, including those with write access to the git repository. |
| 71 |
.SH "CLONING THE REPOSITORY" |
| 72 |
.IX Header "CLONING THE REPOSITORY" |
| 73 |
All of Perl's source code is kept centrally in a Git repository at |
| 74 |
\&\fIgithub.com\fR. |
| 75 |
.PP |
| 76 |
You can make a read-only clone of the repository by running: |
| 77 |
.PP |
| 78 |
.Vb 1 |
| 79 |
\& % git clone [email protected]:Perl/perl5.git perl |
| 80 |
.Ve |
| 81 |
.PP |
| 82 |
If you cannot use that for firewall reasons, you can also clone via http: |
| 83 |
.PP |
| 84 |
.Vb 1 |
| 85 |
\& % git clone https://github.com/Perl/perl5.git perl |
| 86 |
.Ve |
| 87 |
.SH "WORKING WITH THE REPOSITORY" |
| 88 |
.IX Header "WORKING WITH THE REPOSITORY" |
| 89 |
Once you have changed into the repository directory, you can inspect |
| 90 |
it. After a clone the repository will contain a single local branch, |
| 91 |
which will be the current branch as well, as indicated by the asterisk. |
| 92 |
.PP |
| 93 |
.Vb 2 |
| 94 |
\& % git branch |
| 95 |
\& * blead |
| 96 |
.Ve |
| 97 |
.PP |
| 98 |
Using the \-a switch to \f(CW\*(C`branch\*(C'\fR will also show the remote tracking |
| 99 |
branches in the repository: |
| 100 |
.PP |
| 101 |
.Vb 5 |
| 102 |
\& % git branch \-a |
| 103 |
\& * blead |
| 104 |
\& origin/HEAD |
| 105 |
\& origin/blead |
| 106 |
\& ... |
| 107 |
.Ve |
| 108 |
.PP |
| 109 |
The branches that begin with "origin" correspond to the "git remote" |
| 110 |
that you cloned from (which is named "origin"). Each branch on the |
| 111 |
remote will be exactly tracked by these branches. You should NEVER do |
| 112 |
work on these remote tracking branches. You only ever do work in a |
| 113 |
local branch. Local branches can be configured to automerge (on pull) |
| 114 |
from a designated remote tracking branch. This is the case with the |
| 115 |
default branch \f(CW\*(C`blead\*(C'\fR which will be configured to merge from the |
| 116 |
remote tracking branch \f(CW\*(C`origin/blead\*(C'\fR. |
| 117 |
.PP |
| 118 |
You can see recent commits: |
| 119 |
.PP |
| 120 |
.Vb 1 |
| 121 |
\& % git log |
| 122 |
.Ve |
| 123 |
.PP |
| 124 |
And pull new changes from the repository, and update your local |
| 125 |
repository (must be clean first) |
| 126 |
.PP |
| 127 |
.Vb 1 |
| 128 |
\& % git pull |
| 129 |
.Ve |
| 130 |
.PP |
| 131 |
Assuming we are on the branch \f(CW\*(C`blead\*(C'\fR immediately after a pull, this |
| 132 |
command would be more or less equivalent to: |
| 133 |
.PP |
| 134 |
.Vb 2 |
| 135 |
\& % git fetch |
| 136 |
\& % git merge origin/blead |
| 137 |
.Ve |
| 138 |
.PP |
| 139 |
In fact if you want to update your local repository without touching |
| 140 |
your working directory you do: |
| 141 |
.PP |
| 142 |
.Vb 1 |
| 143 |
\& % git fetch |
| 144 |
.Ve |
| 145 |
.PP |
| 146 |
And if you want to update your remote-tracking branches for all defined |
| 147 |
remotes simultaneously you can do |
| 148 |
.PP |
| 149 |
.Vb 1 |
| 150 |
\& % git remote update |
| 151 |
.Ve |
| 152 |
.PP |
| 153 |
Neither of these last two commands will update your working directory, |
| 154 |
however both will update the remote-tracking branches in your |
| 155 |
repository. |
| 156 |
.PP |
| 157 |
To make a local branch of a remote branch: |
| 158 |
.PP |
| 159 |
.Vb 1 |
| 160 |
\& % git checkout \-b maint\-5.10 origin/maint\-5.10 |
| 161 |
.Ve |
| 162 |
.PP |
| 163 |
To switch back to blead: |
| 164 |
.PP |
| 165 |
.Vb 1 |
| 166 |
\& % git checkout blead |
| 167 |
.Ve |
| 168 |
.SS "Finding out your status" |
| 169 |
.IX Subsection "Finding out your status" |
| 170 |
The most common git command you will use will probably be |
| 171 |
.PP |
| 172 |
.Vb 1 |
| 173 |
\& % git status |
| 174 |
.Ve |
| 175 |
.PP |
| 176 |
This command will produce as output a description of the current state |
| 177 |
of the repository, including modified files and unignored untracked |
| 178 |
files, and in addition it will show things like what files have been |
| 179 |
staged for the next commit, and usually some useful information about |
| 180 |
how to change things. For instance the following: |
| 181 |
.PP |
| 182 |
.Vb 3 |
| 183 |
\& % git status |
| 184 |
\& On branch blead |
| 185 |
\& Your branch is ahead of \*(Aqorigin/blead\*(Aq by 1 commit. |
| 186 |
\& |
| 187 |
\& Changes to be committed: |
| 188 |
\& (use "git reset HEAD <file>..." to unstage) |
| 189 |
\& |
| 190 |
\& modified: pod/perlgit.pod |
| 191 |
\& |
| 192 |
\& Changes not staged for commit: |
| 193 |
\& (use "git add <file>..." to update what will be committed) |
| 194 |
\& (use "git checkout \-\- <file>..." to discard changes in working |
| 195 |
\& directory) |
| 196 |
\& |
| 197 |
\& modified: pod/perlgit.pod |
| 198 |
\& |
| 199 |
\& Untracked files: |
| 200 |
\& (use "git add <file>..." to include in what will be committed) |
| 201 |
\& |
| 202 |
\& deliberate.untracked |
| 203 |
.Ve |
| 204 |
.PP |
| 205 |
This shows that there were changes to this document staged for commit, |
| 206 |
and that there were further changes in the working directory not yet |
| 207 |
staged. It also shows that there was an untracked file in the working |
| 208 |
directory, and as you can see shows how to change all of this. It also |
| 209 |
shows that there is one commit on the working branch \f(CW\*(C`blead\*(C'\fR which has |
| 210 |
not been pushed to the \f(CW\*(C`origin\*(C'\fR remote yet. \fBNOTE\fR: This output |
| 211 |
is also what you see as a template if you do not provide a message to |
| 212 |
\&\f(CW\*(C`git commit\*(C'\fR. |
| 213 |
.SS "Patch workflow" |
| 214 |
.IX Subsection "Patch workflow" |
| 215 |
First, please read perlhack for details on hacking the Perl core. |
| 216 |
That document covers many details on how to create a good patch. |
| 217 |
.PP |
| 218 |
If you already have a Perl repository, you should ensure that you're on |
| 219 |
the \fIblead\fR branch, and your repository is up to date: |
| 220 |
.PP |
| 221 |
.Vb 2 |
| 222 |
\& % git checkout blead |
| 223 |
\& % git pull |
| 224 |
.Ve |
| 225 |
.PP |
| 226 |
It's preferable to patch against the latest blead version, since this |
| 227 |
is where new development occurs for all changes other than critical bug |
| 228 |
fixes. Critical bug fix patches should be made against the relevant |
| 229 |
maint branches, or should be submitted with a note indicating all the |
| 230 |
branches where the fix should be applied. |
| 231 |
.PP |
| 232 |
Now that we have everything up to date, we need to create a temporary |
| 233 |
new branch for these changes and switch into it: |
| 234 |
.PP |
| 235 |
.Vb 1 |
| 236 |
\& % git checkout \-b orange |
| 237 |
.Ve |
| 238 |
.PP |
| 239 |
which is the short form of |
| 240 |
.PP |
| 241 |
.Vb 2 |
| 242 |
\& % git branch orange |
| 243 |
\& % git checkout orange |
| 244 |
.Ve |
| 245 |
.PP |
| 246 |
Creating a topic branch makes it easier for the maintainers to rebase |
| 247 |
or merge back into the master blead for a more linear history. If you |
| 248 |
don't work on a topic branch the maintainer has to manually cherry pick |
| 249 |
your changes onto blead before they can be applied. |
| 250 |
.PP |
| 251 |
That'll get you scolded on perl5\-porters, so don't do that. Be Awesome. |
| 252 |
.PP |
| 253 |
Then make your changes. For example, if Leon Brocard changes his name |
| 254 |
to Orange Brocard, we should change his name in the AUTHORS file: |
| 255 |
.PP |
| 256 |
.Vb 1 |
| 257 |
\& % perl \-pi \-e \*(Aqs{Leon Brocard}{Orange Brocard}\*(Aq AUTHORS |
| 258 |
.Ve |
| 259 |
.PP |
| 260 |
You can see what files are changed: |
| 261 |
.PP |
| 262 |
.Vb 4 |
| 263 |
\& % git status |
| 264 |
\& On branch orange |
| 265 |
\& Changes to be committed: |
| 266 |
\& (use "git reset HEAD <file>..." to unstage) |
| 267 |
\& |
| 268 |
\& modified: AUTHORS |
| 269 |
.Ve |
| 270 |
.PP |
| 271 |
And you can see the changes: |
| 272 |
.PP |
| 273 |
.Vb 10 |
| 274 |
\& % git diff |
| 275 |
\& diff \-\-git a/AUTHORS b/AUTHORS |
| 276 |
\& index 293dd70..722c93e 100644 |
| 277 |
\& \-\-\- a/AUTHORS |
| 278 |
\& +++ b/AUTHORS |
| 279 |
\& @@ \-541,7 +541,7 @@ Lars Hecking <[email protected]> |
| 280 |
\& Laszlo Molnar <[email protected]> |
| 281 |
\& Leif Huhn <[email protected]> |
| 282 |
\& Len Johnson <[email protected]> |
| 283 |
\& \-Leon Brocard <[email protected]> |
| 284 |
\& +Orange Brocard <[email protected]> |
| 285 |
\& Les Peters <[email protected]> |
| 286 |
\& Lesley Binks <[email protected]> |
| 287 |
\& Lincoln D. Stein <[email protected]> |
| 288 |
.Ve |
| 289 |
.PP |
| 290 |
Now commit your change locally: |
| 291 |
.PP |
| 292 |
.Vb 3 |
| 293 |
\& % git commit \-a \-m \*(AqRename Leon Brocard to Orange Brocard\*(Aq |
| 294 |
\& Created commit 6196c1d: Rename Leon Brocard to Orange Brocard |
| 295 |
\& 1 files changed, 1 insertions(+), 1 deletions(\-) |
| 296 |
.Ve |
| 297 |
.PP |
| 298 |
The \f(CW\*(C`\-a\*(C'\fR option is used to include all files that git tracks that you |
| 299 |
have changed. If at this time, you only want to commit some of the |
| 300 |
files you have worked on, you can omit the \f(CW\*(C`\-a\*(C'\fR and use the command |
| 301 |
\&\f(CW\*(C`git\ add\ \fR\f(CIFILE\ ...\fR\f(CW\*(C'\fR before doing the commit. \f(CW\*(C`git\ add\ \-\-interactive\*(C'\fR allows you to even just commit portions of files |
| 302 |
instead of all the changes in them. |
| 303 |
.PP |
| 304 |
The \f(CW\*(C`\-m\*(C'\fR option is used to specify the commit message. If you omit it, |
| 305 |
git will open a text editor for you to compose the message |
| 306 |
interactively. This is useful when the changes are more complex than |
| 307 |
the sample given here, and, depending on the editor, to know that the |
| 308 |
first line of the commit message doesn't exceed the 50 character legal |
| 309 |
maximum. See "Commit message" in perlhack for more information about what |
| 310 |
makes a good commit message. |
| 311 |
.PP |
| 312 |
Once you've finished writing your commit message and exited your |
| 313 |
editor, git will write your change to disk and tell you something like |
| 314 |
this: |
| 315 |
.PP |
| 316 |
.Vb 2 |
| 317 |
\& Created commit daf8e63: explain git status and stuff about remotes |
| 318 |
\& 1 files changed, 83 insertions(+), 3 deletions(\-) |
| 319 |
.Ve |
| 320 |
.PP |
| 321 |
If you re-run \f(CW\*(C`git status\*(C'\fR, you should see something like this: |
| 322 |
.PP |
| 323 |
.Vb 4 |
| 324 |
\& % git status |
| 325 |
\& On branch orange |
| 326 |
\& Untracked files: |
| 327 |
\& (use "git add <file>..." to include in what will be committed) |
| 328 |
\& |
| 329 |
\& deliberate.untracked |
| 330 |
\& |
| 331 |
\& nothing added to commit but untracked files present (use "git add" to |
| 332 |
\& track) |
| 333 |
.Ve |
| 334 |
.PP |
| 335 |
When in doubt, before you do anything else, check your status and read |
| 336 |
it carefully, many questions are answered directly by the git status |
| 337 |
output. |
| 338 |
.PP |
| 339 |
You can examine your last commit with: |
| 340 |
.PP |
| 341 |
.Vb 1 |
| 342 |
\& % git show HEAD |
| 343 |
.Ve |
| 344 |
.PP |
| 345 |
and if you are not happy with either the description or the patch |
| 346 |
itself you can fix it up by editing the files once more and then issue: |
| 347 |
.PP |
| 348 |
.Vb 1 |
| 349 |
\& % git commit \-a \-\-amend |
| 350 |
.Ve |
| 351 |
.PP |
| 352 |
Now, create a fork on GitHub to push your branch to, and add it as a |
| 353 |
remote if you haven't already, as described in the GitHub documentation |
| 354 |
at <https://help.github.com/en/articles/working\-with\-forks>: |
| 355 |
.PP |
| 356 |
.Vb 1 |
| 357 |
\& % git remote add fork [email protected]:MyUser/perl5.git |
| 358 |
.Ve |
| 359 |
.PP |
| 360 |
And push the branch to your fork: |
| 361 |
.PP |
| 362 |
.Vb 1 |
| 363 |
\& % git push \-u fork orange |
| 364 |
.Ve |
| 365 |
.PP |
| 366 |
You should now submit a Pull Request (PR) on GitHub from the new branch |
| 367 |
to blead. For more information, see the GitHub documentation at |
| 368 |
<https://help.github.com/en/articles/creating\-a\-pull\-request\-from\-a\-fork>. |
| 369 |
.PP |
| 370 |
You can also send patch files to |
| 371 |
perl5\[email protected] <mailto:[email protected]> directly if the |
| 372 |
patch is not ready to be applied, but intended for discussion. |
| 373 |
.PP |
| 374 |
To create a patch file for all your local changes: |
| 375 |
.PP |
| 376 |
.Vb 2 |
| 377 |
\& % git format\-patch \-M blead.. |
| 378 |
\& 0001\-Rename\-Leon\-Brocard\-to\-Orange\-Brocard.patch |
| 379 |
.Ve |
| 380 |
.PP |
| 381 |
Or for a lot of changes, e.g. from a topic branch: |
| 382 |
.PP |
| 383 |
.Vb 1 |
| 384 |
\& % git format\-patch \-\-stdout \-M blead.. > topic\-branch\-changes.patch |
| 385 |
.Ve |
| 386 |
.PP |
| 387 |
If you want to delete your temporary branch, you may do so with: |
| 388 |
.PP |
| 389 |
.Vb 6 |
| 390 |
\& % git checkout blead |
| 391 |
\& % git branch \-d orange |
| 392 |
\& error: The branch \*(Aqorange\*(Aq is not an ancestor of your current HEAD. |
| 393 |
\& If you are sure you want to delete it, run \*(Aqgit branch \-D orange\*(Aq. |
| 394 |
\& % git branch \-D orange |
| 395 |
\& Deleted branch orange. |
| 396 |
.Ve |
| 397 |
.SS "A note on derived files" |
| 398 |
.IX Subsection "A note on derived files" |
| 399 |
Be aware that many files in the distribution are derivative\-\-avoid |
| 400 |
patching them, because git won't see the changes to them, and the build |
| 401 |
process will overwrite them. Patch the originals instead. Most |
| 402 |
utilities (like perldoc) are in this category, i.e. patch |
| 403 |
\&\fIutils/perldoc.PL\fR rather than \fIutils/perldoc\fR. Similarly, don't |
| 404 |
create patches for files under \fR\f(CI$src_root\fR\fI/ext\fR from their copies found |
| 405 |
in \fI\fR\f(CI$install_root\fR\fI/lib\fR. If you are unsure about the proper location of |
| 406 |
a file that may have gotten copied while building the source |
| 407 |
distribution, consult the \fIMANIFEST\fR. |
| 408 |
.SS "Cleaning a working directory" |
| 409 |
.IX Subsection "Cleaning a working directory" |
| 410 |
The command \f(CW\*(C`git clean\*(C'\fR can with varying arguments be used as a |
| 411 |
replacement for \f(CW\*(C`make clean\*(C'\fR. |
| 412 |
.PP |
| 413 |
To reset your working directory to a pristine condition you can do: |
| 414 |
.PP |
| 415 |
.Vb 1 |
| 416 |
\& % git clean \-dxf |
| 417 |
.Ve |
| 418 |
.PP |
| 419 |
However, be aware this will delete ALL untracked content. You can use |
| 420 |
.PP |
| 421 |
.Vb 1 |
| 422 |
\& % git clean \-Xf |
| 423 |
.Ve |
| 424 |
.PP |
| 425 |
to remove all ignored untracked files, such as build and test |
| 426 |
byproduct, but leave any manually created files alone. |
| 427 |
.PP |
| 428 |
If you only want to cancel some uncommitted edits, you can use \f(CW\*(C`git |
| 429 |
checkout\*(C'\fR and give it a list of files to be reverted, or \f(CW\*(C`git checkout |
| 430 |
\&\-f\*(C'\fR to revert them all. |
| 431 |
.PP |
| 432 |
If you want to cancel one or several commits, you can use \f(CW\*(C`git reset\*(C'\fR. |
| 433 |
.SS Bisecting |
| 434 |
.IX Subsection "Bisecting" |
| 435 |
\&\f(CW\*(C`git\*(C'\fR provides a built-in way to determine which commit should be blamed |
| 436 |
for introducing a given bug. \f(CW\*(C`git bisect\*(C'\fR performs a binary search of |
| 437 |
history to locate the first failing commit. It is fast, powerful and |
| 438 |
flexible, but requires some setup and to automate the process an auxiliary |
| 439 |
shell script is needed. |
| 440 |
.PP |
| 441 |
The core provides a wrapper program, \fIPorting/bisect.pl\fR, which attempts to |
| 442 |
simplify as much as possible, making bisecting as simple as running a Perl |
| 443 |
one-liner. For example, if you want to know when this became an error: |
| 444 |
.PP |
| 445 |
.Vb 1 |
| 446 |
\& perl \-e \*(Aqmy $x := 2\*(Aq |
| 447 |
.Ve |
| 448 |
.PP |
| 449 |
you simply run this: |
| 450 |
.PP |
| 451 |
.Vb 1 |
| 452 |
\& .../Porting/bisect.pl \-e \*(Aqmy $x := 2;\*(Aq |
| 453 |
.Ve |
| 454 |
.PP |
| 455 |
Using \fIPorting/bisect.pl\fR, with one command (and no other files) it's easy to |
| 456 |
find out |
| 457 |
.IP \(bu 4 |
| 458 |
Which commit caused this example code to break? |
| 459 |
.IP \(bu 4 |
| 460 |
Which commit caused this example code to start working? |
| 461 |
.IP \(bu 4 |
| 462 |
Which commit added the first file to match this regex? |
| 463 |
.IP \(bu 4 |
| 464 |
Which commit removed the last file to match this regex? |
| 465 |
.PP |
| 466 |
usually without needing to know which versions of perl to use as start and |
| 467 |
end revisions, as \fIPorting/bisect.pl\fR automatically searches to find the |
| 468 |
earliest stable version for which the test case passes. Run |
| 469 |
\&\f(CW\*(C`Porting/bisect.pl \-\-help\*(C'\fR for the full documentation, including how to |
| 470 |
set the \f(CW\*(C`Configure\*(C'\fR and build time options. |
| 471 |
.PP |
| 472 |
If you require more flexibility than \fIPorting/bisect.pl\fR has to offer, you'll |
| 473 |
need to run \f(CW\*(C`git bisect\*(C'\fR yourself. It's most useful to use \f(CW\*(C`git bisect run\*(C'\fR |
| 474 |
to automate the building and testing of perl revisions. For this you'll need |
| 475 |
a shell script for \f(CW\*(C`git\*(C'\fR to call to test a particular revision. An example |
| 476 |
script is \fIPorting/bisect\-example.sh\fR, which you should copy \fBoutside\fR of |
| 477 |
the repository, as the bisect process will reset the state to a clean checkout |
| 478 |
as it runs. The instructions below assume that you copied it as \fI~/run\fR and |
| 479 |
then edited it as appropriate. |
| 480 |
.PP |
| 481 |
You first enter in bisect mode with: |
| 482 |
.PP |
| 483 |
.Vb 1 |
| 484 |
\& % git bisect start |
| 485 |
.Ve |
| 486 |
.PP |
| 487 |
For example, if the bug is present on \f(CW\*(C`HEAD\*(C'\fR but wasn't in 5.10.0, |
| 488 |
\&\f(CW\*(C`git\*(C'\fR will learn about this when you enter: |
| 489 |
.PP |
| 490 |
.Vb 3 |
| 491 |
\& % git bisect bad |
| 492 |
\& % git bisect good perl\-5.10.0 |
| 493 |
\& Bisecting: 853 revisions left to test after this |
| 494 |
.Ve |
| 495 |
.PP |
| 496 |
This results in checking out the median commit between \f(CW\*(C`HEAD\*(C'\fR and |
| 497 |
\&\f(CW\*(C`perl\-5.10.0\*(C'\fR. You can then run the bisecting process with: |
| 498 |
.PP |
| 499 |
.Vb 1 |
| 500 |
\& % git bisect run ~/run |
| 501 |
.Ve |
| 502 |
.PP |
| 503 |
When the first bad commit is isolated, \f(CW\*(C`git bisect\*(C'\fR will tell you so: |
| 504 |
.PP |
| 505 |
.Vb 4 |
| 506 |
\& ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit |
| 507 |
\& commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 |
| 508 |
\& Author: Dave Mitchell <[email protected]> |
| 509 |
\& Date: Sat Feb 9 14:56:23 2008 +0000 |
| 510 |
\& |
| 511 |
\& [perl #49472] Attributes + Unknown Error |
| 512 |
\& ... |
| 513 |
\& |
| 514 |
\& bisect run success |
| 515 |
.Ve |
| 516 |
.PP |
| 517 |
You can peek into the bisecting process with \f(CW\*(C`git bisect log\*(C'\fR and |
| 518 |
\&\f(CW\*(C`git bisect visualize\*(C'\fR. \f(CW\*(C`git bisect reset\*(C'\fR will get you out of bisect |
| 519 |
mode. |
| 520 |
.PP |
| 521 |
Please note that the first \f(CW\*(C`good\*(C'\fR state must be an ancestor of the |
| 522 |
first \f(CW\*(C`bad\*(C'\fR state. If you want to search for the commit that \fIsolved\fR |
| 523 |
some bug, you have to negate your test case (i.e. exit with \f(CW1\fR if OK |
| 524 |
and \f(CW0\fR if not) and still mark the lower bound as \f(CW\*(C`good\*(C'\fR and the |
| 525 |
upper as \f(CW\*(C`bad\*(C'\fR. The "first bad commit" has then to be understood as |
| 526 |
the "first commit where the bug is solved". |
| 527 |
.PP |
| 528 |
\&\f(CW\*(C`git help bisect\*(C'\fR has much more information on how you can tweak your |
| 529 |
binary searches. |
| 530 |
.PP |
| 531 |
Following bisection you may wish to configure, build and test perl at |
| 532 |
commits identified by the bisection process. Sometimes, particularly |
| 533 |
with older perls, \f(CW\*(C`make\*(C'\fR may fail during this process. In this case |
| 534 |
you may be able to patch the source code at the older commit point. To |
| 535 |
do so, please follow the suggestions provided in |
| 536 |
"Building perl at older commits" in perlhack. |
| 537 |
.SS "Topic branches and rewriting history" |
| 538 |
.IX Subsection "Topic branches and rewriting history" |
| 539 |
Individual committers should create topic branches under |
| 540 |
\&\fByourname\fR/\fBsome_descriptive_name\fR: |
| 541 |
.PP |
| 542 |
.Vb 4 |
| 543 |
\& % branch="$yourname/$some_descriptive_name" |
| 544 |
\& % git checkout \-b $branch |
| 545 |
\& ... do local edits, commits etc ... |
| 546 |
\& % git push origin \-u $branch |
| 547 |
.Ve |
| 548 |
.PP |
| 549 |
Should you be stuck with an ancient version of git (prior to 1.7), then |
| 550 |
\&\f(CW\*(C`git push\*(C'\fR will not have the \f(CW\*(C`\-u\*(C'\fR switch, and you have to replace the |
| 551 |
last step with the following sequence: |
| 552 |
.PP |
| 553 |
.Vb 3 |
| 554 |
\& % git push origin $branch:refs/heads/$branch |
| 555 |
\& % git config branch.$branch.remote origin |
| 556 |
\& % git config branch.$branch.merge refs/heads/$branch |
| 557 |
.Ve |
| 558 |
.PP |
| 559 |
If you want to make changes to someone else's topic branch, you should |
| 560 |
check with its creator before making any change to it. |
| 561 |
.PP |
| 562 |
You |
| 563 |
might sometimes find that the original author has edited the branch's |
| 564 |
history. There are lots of good reasons for this. Sometimes, an author |
| 565 |
might simply be rebasing the branch onto a newer source point. |
| 566 |
Sometimes, an author might have found an error in an early commit which |
| 567 |
they wanted to fix before merging the branch to blead. |
| 568 |
.PP |
| 569 |
Currently the master repository is configured to forbid |
| 570 |
non-fast-forward merges. This means that the branches within can not be |
| 571 |
rebased and pushed as a single step. |
| 572 |
.PP |
| 573 |
The only way you will ever be allowed to rebase or modify the history |
| 574 |
of a pushed branch is to delete it and push it as a new branch under |
| 575 |
the same name. Please think carefully about doing this. It may be |
| 576 |
better to sequentially rename your branches so that it is easier for |
| 577 |
others working with you to cherry-pick their local changes onto the new |
| 578 |
version. (XXX: needs explanation). |
| 579 |
.PP |
| 580 |
If you want to rebase a personal topic branch, you will have to delete |
| 581 |
your existing topic branch and push as a new version of it. You can do |
| 582 |
this via the following formula (see the explanation about \f(CW\*(C`refspec\*(C'\fR's |
| 583 |
in the git push documentation for details) after you have rebased your |
| 584 |
branch: |
| 585 |
.PP |
| 586 |
.Vb 4 |
| 587 |
\& # first rebase |
| 588 |
\& % git checkout $user/$topic |
| 589 |
\& % git fetch |
| 590 |
\& % git rebase origin/blead |
| 591 |
\& |
| 592 |
\& # then "delete\-and\-push" |
| 593 |
\& % git push origin :$user/$topic |
| 594 |
\& % git push origin $user/$topic |
| 595 |
.Ve |
| 596 |
.PP |
| 597 |
\&\fBNOTE:\fR it is forbidden at the repository level to delete any of the |
| 598 |
"primary" branches. That is any branch matching |
| 599 |
\&\f(CW\*(C`m!^(blead|maint|perl)!\*(C'\fR. Any attempt to do so will result in git |
| 600 |
producing an error like this: |
| 601 |
.PP |
| 602 |
.Vb 7 |
| 603 |
\& % git push origin :blead |
| 604 |
\& *** It is forbidden to delete blead/maint branches in this repository |
| 605 |
\& error: hooks/update exited with error code 1 |
| 606 |
\& error: hook declined to update refs/heads/blead |
| 607 |
\& To ssh://perl5.git.perl.org/perl |
| 608 |
\& ! [remote rejected] blead (hook declined) |
| 609 |
\& error: failed to push some refs to \*(Aqssh://perl5.git.perl.org/perl\*(Aq |
| 610 |
.Ve |
| 611 |
.PP |
| 612 |
As a matter of policy we do \fBnot\fR edit the history of the blead and |
| 613 |
maint\-* branches. If a typo (or worse) sneaks into a commit to blead or |
| 614 |
maint\-*, we'll fix it in another commit. The only types of updates |
| 615 |
allowed on these branches are "fast-forwards", where all history is |
| 616 |
preserved. |
| 617 |
.PP |
| 618 |
Annotated tags in the canonical perl.git repository will never be |
| 619 |
deleted or modified. Think long and hard about whether you want to push |
| 620 |
a local tag to perl.git before doing so. (Pushing simple tags is |
| 621 |
not allowed.) |
| 622 |
.SS Grafts |
| 623 |
.IX Subsection "Grafts" |
| 624 |
The perl history contains one mistake which was not caught in the |
| 625 |
conversion: a merge was recorded in the history between blead and |
| 626 |
maint\-5.10 where no merge actually occurred. Due to the nature of git, |
| 627 |
this is now impossible to fix in the public repository. You can remove |
| 628 |
this mis-merge locally by adding the following line to your |
| 629 |
\&\f(CW\*(C`.git/info/grafts\*(C'\fR file: |
| 630 |
.PP |
| 631 |
.Vb 1 |
| 632 |
\& 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930 |
| 633 |
.Ve |
| 634 |
.PP |
| 635 |
It is particularly important to have this graft line if any bisecting |
| 636 |
is done in the area of the "merge" in question. |
| 637 |
.SH "WRITE ACCESS TO THE GIT REPOSITORY" |
| 638 |
.IX Header "WRITE ACCESS TO THE GIT REPOSITORY" |
| 639 |
Once you have write access, you will need to modify the URL for the |
| 640 |
origin remote to enable pushing. Edit \fI.git/config\fR with the |
| 641 |
\&\fBgit\-config\fR\|(1) command: |
| 642 |
.PP |
| 643 |
.Vb 1 |
| 644 |
\& % git config remote.origin.url [email protected]:Perl/perl5.git |
| 645 |
.Ve |
| 646 |
.PP |
| 647 |
You can also set up your user name and e\-mail address. Most people do |
| 648 |
this once globally in their \fI~/.gitconfig\fR by doing something like: |
| 649 |
.PP |
| 650 |
.Vb 2 |
| 651 |
\& % git config \-\-global user.name "Ævar Arnfjörð Bjarmason" |
| 652 |
\& % git config \-\-global user.email [email protected] |
| 653 |
.Ve |
| 654 |
.PP |
| 655 |
However, if you'd like to override that just for perl, |
| 656 |
execute something like the following in \fIperl\fR: |
| 657 |
.PP |
| 658 |
.Vb 1 |
| 659 |
\& % git config user.email [email protected] |
| 660 |
.Ve |
| 661 |
.PP |
| 662 |
It is also possible to keep \f(CW\*(C`origin\*(C'\fR as a git remote, and add a new |
| 663 |
remote for ssh access: |
| 664 |
.PP |
| 665 |
.Vb 1 |
| 666 |
\& % git remote add camel [email protected]:Perl/perl5.git |
| 667 |
.Ve |
| 668 |
.PP |
| 669 |
This allows you to update your local repository by pulling from |
| 670 |
\&\f(CW\*(C`origin\*(C'\fR, which is faster and doesn't require you to authenticate, and |
| 671 |
to push your changes back with the \f(CW\*(C`camel\*(C'\fR remote: |
| 672 |
.PP |
| 673 |
.Vb 2 |
| 674 |
\& % git fetch camel |
| 675 |
\& % git push camel |
| 676 |
.Ve |
| 677 |
.PP |
| 678 |
The \f(CW\*(C`fetch\*(C'\fR command just updates the \f(CW\*(C`camel\*(C'\fR refs, as the objects |
| 679 |
themselves should have been fetched when pulling from \f(CW\*(C`origin\*(C'\fR. |
| 680 |
.SS "Working with Github pull requests" |
| 681 |
.IX Subsection "Working with Github pull requests" |
| 682 |
Pull requests typically originate from outside of the \f(CW\*(C`Perl/perl.git\*(C'\fR |
| 683 |
repository, so if you want to test or work with it locally a vanilla |
| 684 |
\&\f(CW\*(C`git fetch\*(C'\fR from the \f(CW\*(C`Perl/perl5.git\*(C'\fR repository won't fetch it. |
| 685 |
.PP |
| 686 |
However Github does provide a mechanism to fetch a pull request to a |
| 687 |
local branch. They are available on Github remotes under \f(CW\*(C`pull/\*(C'\fR, so |
| 688 |
you can use \f(CW\*(C`git fetch pull/\fR\f(CIPRID\fR\f(CW/head:\fR\f(CIlocalname\fR\f(CW\*(C'\fR to make a |
| 689 |
local copy. eg. to fetch pull request 9999 to the local branch |
| 690 |
\&\f(CW\*(C`local\-branch\-name\*(C'\fR run: |
| 691 |
.PP |
| 692 |
.Vb 1 |
| 693 |
\& git fetch origin pull/9999/head:local\-branch\-name |
| 694 |
.Ve |
| 695 |
.PP |
| 696 |
and then: |
| 697 |
.PP |
| 698 |
.Vb 1 |
| 699 |
\& git checkout local\-branch\-name |
| 700 |
.Ve |
| 701 |
.PP |
| 702 |
Note: this branch is not rebased on \f(CW\*(C`blead\*(C'\fR, so instead of the |
| 703 |
checkout above, you might want: |
| 704 |
.PP |
| 705 |
.Vb 1 |
| 706 |
\& git rebase origin/blead local\-branch\-name |
| 707 |
.Ve |
| 708 |
.PP |
| 709 |
which rebases \f(CW\*(C`local\-branch\-name\*(C'\fR on \f(CW\*(C`blead\*(C'\fR, and checks it out. |
| 710 |
.PP |
| 711 |
Alternatively you can configure the remote to fetch all pull requests |
| 712 |
as remote-tracking branches. To do this edit the remote in |
| 713 |
\&\fI.git/config\fR, for example if your github remote is \f(CW\*(C`origin\*(C'\fR you'd |
| 714 |
have: |
| 715 |
.PP |
| 716 |
.Vb 3 |
| 717 |
\& [remote "origin"] |
| 718 |
\& url = [email protected]:/Perl/perl5.git |
| 719 |
\& fetch = +refs/heads/*:refs/remotes/origin/* |
| 720 |
.Ve |
| 721 |
.PP |
| 722 |
Add a line to map the remote pull request branches to remote-tracking |
| 723 |
branches: |
| 724 |
.PP |
| 725 |
.Vb 4 |
| 726 |
\& [remote "origin"] |
| 727 |
\& url = [email protected]:/Perl/perl5.git |
| 728 |
\& fetch = +refs/heads/*:refs/remotes/origin/* |
| 729 |
\& fetch = +refs/pull/*/head:refs/remotes/origin/pull/* |
| 730 |
.Ve |
| 731 |
.PP |
| 732 |
and then do a fetch as normal: |
| 733 |
.PP |
| 734 |
.Vb 1 |
| 735 |
\& git fetch origin |
| 736 |
.Ve |
| 737 |
.PP |
| 738 |
This will create a remote-tracking branch for every pull request, including |
| 739 |
closed requests. |
| 740 |
.PP |
| 741 |
To remove those remote-tracking branches, remove the line added above |
| 742 |
and prune: |
| 743 |
.PP |
| 744 |
.Vb 1 |
| 745 |
\& git fetch \-p origin # or git remote prune origin |
| 746 |
.Ve |
| 747 |
.SS "Accepting a patch" |
| 748 |
.IX Subsection "Accepting a patch" |
| 749 |
If you have received a patch file generated using the above section, |
| 750 |
you should try out the patch. |
| 751 |
.PP |
| 752 |
First we need to create a temporary new branch for these changes and |
| 753 |
switch into it: |
| 754 |
.PP |
| 755 |
.Vb 1 |
| 756 |
\& % git checkout \-b experimental |
| 757 |
.Ve |
| 758 |
.PP |
| 759 |
Patches that were formatted by \f(CW\*(C`git format\-patch\*(C'\fR are applied with |
| 760 |
\&\f(CW\*(C`git am\*(C'\fR: |
| 761 |
.PP |
| 762 |
.Vb 2 |
| 763 |
\& % git am 0001\-Rename\-Leon\-Brocard\-to\-Orange\-Brocard.patch |
| 764 |
\& Applying Rename Leon Brocard to Orange Brocard |
| 765 |
.Ve |
| 766 |
.PP |
| 767 |
Note that some UNIX mail systems can mess with text attachments containing |
| 768 |
\&'From '. This will fix them up: |
| 769 |
.PP |
| 770 |
.Vb 2 |
| 771 |
\& % perl \-pi \-e\*(Aqs/^>From /From /\*(Aq \e |
| 772 |
\& 0001\-Rename\-Leon\-Brocard\-to\-Orange\-Brocard.patch |
| 773 |
.Ve |
| 774 |
.PP |
| 775 |
If just a raw diff is provided, it is also possible use this two-step |
| 776 |
process: |
| 777 |
.PP |
| 778 |
.Vb 3 |
| 779 |
\& % git apply bugfix.diff |
| 780 |
\& % git commit \-a \-m "Some fixing" \e |
| 781 |
\& \-\-author="That Guy <[email protected]>" |
| 782 |
.Ve |
| 783 |
.PP |
| 784 |
Now we can inspect the change: |
| 785 |
.PP |
| 786 |
.Vb 4 |
| 787 |
\& % git show HEAD |
| 788 |
\& commit b1b3dab48344cff6de4087efca3dbd63548ab5e2 |
| 789 |
\& Author: Leon Brocard <[email protected]> |
| 790 |
\& Date: Fri Dec 19 17:02:59 2008 +0000 |
| 791 |
\& |
| 792 |
\& Rename Leon Brocard to Orange Brocard |
| 793 |
\& |
| 794 |
\& diff \-\-git a/AUTHORS b/AUTHORS |
| 795 |
\& index 293dd70..722c93e 100644 |
| 796 |
\& \-\-\- a/AUTHORS |
| 797 |
\& +++ b/AUTHORS |
| 798 |
\& @@ \-541,7 +541,7 @@ Lars Hecking <[email protected]> |
| 799 |
\& Laszlo Molnar <[email protected]> |
| 800 |
\& Leif Huhn <[email protected]> |
| 801 |
\& Len Johnson <[email protected]> |
| 802 |
\& \-Leon Brocard <[email protected]> |
| 803 |
\& +Orange Brocard <[email protected]> |
| 804 |
\& Les Peters <[email protected]> |
| 805 |
\& Lesley Binks <[email protected]> |
| 806 |
\& Lincoln D. Stein <[email protected]> |
| 807 |
.Ve |
| 808 |
.PP |
| 809 |
If you are a committer to Perl and you think the patch is good, you can |
| 810 |
then merge it into blead then push it out to the main repository: |
| 811 |
.PP |
| 812 |
.Vb 3 |
| 813 |
\& % git checkout blead |
| 814 |
\& % git merge experimental |
| 815 |
\& % git push origin blead |
| 816 |
.Ve |
| 817 |
.PP |
| 818 |
If you want to delete your temporary branch, you may do so with: |
| 819 |
.PP |
| 820 |
.Vb 7 |
| 821 |
\& % git checkout blead |
| 822 |
\& % git branch \-d experimental |
| 823 |
\& error: The branch \*(Aqexperimental\*(Aq is not an ancestor of your current |
| 824 |
\& HEAD. If you are sure you want to delete it, run \*(Aqgit branch \-D |
| 825 |
\& experimental\*(Aq. |
| 826 |
\& % git branch \-D experimental |
| 827 |
\& Deleted branch experimental. |
| 828 |
.Ve |
| 829 |
.SS "Committing to blead" |
| 830 |
.IX Subsection "Committing to blead" |
| 831 |
The 'blead' branch will become the next production release of Perl. |
| 832 |
.PP |
| 833 |
Before pushing \fIany\fR local change to blead, it's incredibly important |
| 834 |
that you do a few things, lest other committers come after you with |
| 835 |
pitchforks and torches: |
| 836 |
.IP \(bu 4 |
| 837 |
Make sure you have a good commit message. See "Commit |
| 838 |
message" in perlhack for details. |
| 839 |
.IP \(bu 4 |
| 840 |
Run the test suite. You might not think that one typo fix would break a |
| 841 |
test file. You'd be wrong. Here's an example of where not running the |
| 842 |
suite caused problems. A patch was submitted that added a couple of |
| 843 |
tests to an existing \fI.t\fR. It couldn't possibly affect anything else, so |
| 844 |
no need to test beyond the single affected \fI.t\fR, right? But, the |
| 845 |
submitter's email address had changed since the last of their |
| 846 |
submissions, and this caused other tests to fail. Running the test |
| 847 |
target given in the next item would have caught this problem. |
| 848 |
.IP \(bu 4 |
| 849 |
If you don't run the full test suite, at least \f(CW\*(C`make test_porting\*(C'\fR. |
| 850 |
This will run basic sanity checks. To see which sanity checks, have a |
| 851 |
look in \fIt/porting\fR. |
| 852 |
.IP \(bu 4 |
| 853 |
If you make any changes that affect miniperl or core routines that have |
| 854 |
different code paths for miniperl, be sure to run \f(CW\*(C`make minitest\*(C'\fR. |
| 855 |
This will catch problems that even the full test suite will not catch |
| 856 |
because it runs a subset of tests under miniperl rather than perl. |
| 857 |
.SS "On merging and rebasing" |
| 858 |
.IX Subsection "On merging and rebasing" |
| 859 |
Simple, one-off commits pushed to the 'blead' branch should be simple |
| 860 |
commits that apply cleanly. In other words, you should make sure your |
| 861 |
work is committed against the current position of blead, so that you can |
| 862 |
push back to the master repository without merging. |
| 863 |
.PP |
| 864 |
Sometimes, blead will move while you're building or testing your |
| 865 |
changes. When this happens, your push will be rejected with a message |
| 866 |
like this: |
| 867 |
.PP |
| 868 |
.Vb 7 |
| 869 |
\& To ssh://perl5.git.perl.org/perl.git |
| 870 |
\& ! [rejected] blead \-> blead (non\-fast\-forward) |
| 871 |
\& error: failed to push some refs to \*(Aqssh://perl5.git.perl.org/perl.git\*(Aq |
| 872 |
\& To prevent you from losing history, non\-fast\-forward updates were |
| 873 |
\& rejected Merge the remote changes (e.g. \*(Aqgit pull\*(Aq) before pushing |
| 874 |
\& again. See the \*(AqNote about fast\-forwards\*(Aq section of \*(Aqgit push \-\-help\*(Aq |
| 875 |
\& for details. |
| 876 |
.Ve |
| 877 |
.PP |
| 878 |
When this happens, you can just \fIrebase\fR your work against the new |
| 879 |
position of blead, like this (assuming your remote for the master |
| 880 |
repository is "p5p"): |
| 881 |
.PP |
| 882 |
.Vb 2 |
| 883 |
\& % git fetch p5p |
| 884 |
\& % git rebase p5p/blead |
| 885 |
.Ve |
| 886 |
.PP |
| 887 |
You will see your commits being re-applied, and you will then be able to |
| 888 |
push safely. More information about rebasing can be found in the |
| 889 |
documentation for the \fBgit\-rebase\fR\|(1) command. |
| 890 |
.PP |
| 891 |
For larger sets of commits that only make sense together, or that would |
| 892 |
benefit from a summary of the set's purpose, you should use a merge |
| 893 |
commit. You should perform your work on a topic branch, which you should regularly rebase |
| 894 |
against blead to ensure that your code is not broken by blead moving. |
| 895 |
When you have finished your work, please perform a final rebase and |
| 896 |
test. Linear history is something that gets lost with every |
| 897 |
commit on blead, but a final rebase makes the history linear |
| 898 |
again, making it easier for future maintainers to see what has |
| 899 |
happened. Rebase as follows (assuming your work was on the |
| 900 |
branch \f(CW\*(C`committer/somework\*(C'\fR): |
| 901 |
.PP |
| 902 |
.Vb 2 |
| 903 |
\& % git checkout committer/somework |
| 904 |
\& % git rebase blead |
| 905 |
.Ve |
| 906 |
.PP |
| 907 |
Then you can merge it into master like this: |
| 908 |
.PP |
| 909 |
.Vb 3 |
| 910 |
\& % git checkout blead |
| 911 |
\& % git merge \-\-no\-ff \-\-no\-commit committer/somework |
| 912 |
\& % git commit \-a |
| 913 |
.Ve |
| 914 |
.PP |
| 915 |
The switches above deserve explanation. \f(CW\*(C`\-\-no\-ff\*(C'\fR indicates that even |
| 916 |
if all your work can be applied linearly against blead, a merge commit |
| 917 |
should still be prepared. This ensures that all your work will be shown |
| 918 |
as a side branch, with all its commits merged into the mainstream blead |
| 919 |
by the merge commit. |
| 920 |
.PP |
| 921 |
\&\f(CW\*(C`\-\-no\-commit\*(C'\fR means that the merge commit will be \fIprepared\fR but not |
| 922 |
\&\fIcommitted\fR. The commit is then actually performed when you run the |
| 923 |
next command, which will bring up your editor to describe the commit. |
| 924 |
Without \f(CW\*(C`\-\-no\-commit\*(C'\fR, the commit would be made with nearly no useful |
| 925 |
message, which would greatly diminish the value of the merge commit as a |
| 926 |
placeholder for the work's description. |
| 927 |
.PP |
| 928 |
When describing the merge commit, explain the purpose of the branch, and |
| 929 |
keep in mind that this description will probably be used by the |
| 930 |
eventual release engineer when reviewing the next perldelta document. |
| 931 |
.PP |
| 932 |
If the subsequent \fIpush\fR fails then you must be careful on how you \fIrebase\fR. |
| 933 |
If you use |
| 934 |
.PP |
| 935 |
.Vb 1 |
| 936 |
\& % git rebase p5p/blead |
| 937 |
.Ve |
| 938 |
.PP |
| 939 |
or |
| 940 |
.PP |
| 941 |
.Vb 1 |
| 942 |
\& % git pull \-\-rebase |
| 943 |
.Ve |
| 944 |
.PP |
| 945 |
then your carefully created merge commit will be lost! To avoid this you |
| 946 |
can use: |
| 947 |
.PP |
| 948 |
.Vb 2 |
| 949 |
\& % git fetch p5p |
| 950 |
\& % git rebase \-\-rebase\-merges p5p/blead |
| 951 |
.Ve |
| 952 |
.PP |
| 953 |
This will recreate your merge commit. |
| 954 |
.PP |
| 955 |
(Should you be stuck with an older version of git (prior to 2.18), then |
| 956 |
\&\f(CW\*(C`git rebase\*(C'\fR will not have the \f(CW\*(C`\-\-rebase\-merges\*(C'\fR switch, instead you |
| 957 |
have to use the \f(CW\*(C`\-\-preserve\-merges\*(C'\fR switch.) |
| 958 |
.SS "Committing to maintenance versions" |
| 959 |
.IX Subsection "Committing to maintenance versions" |
| 960 |
Maintenance versions should only be altered to add critical bug fixes, |
| 961 |
see perlpolicy. |
| 962 |
.PP |
| 963 |
To commit to a maintenance version of perl, you need to create a local |
| 964 |
tracking branch: |
| 965 |
.PP |
| 966 |
.Vb 1 |
| 967 |
\& % git checkout \-\-track \-b maint\-5.005 origin/maint\-5.005 |
| 968 |
.Ve |
| 969 |
.PP |
| 970 |
This creates a local branch named \f(CW\*(C`maint\-5.005\*(C'\fR, which tracks the |
| 971 |
remote branch \f(CW\*(C`origin/maint\-5.005\*(C'\fR. Then you can pull, commit, merge |
| 972 |
and push as before. |
| 973 |
.PP |
| 974 |
You can also cherry-pick commits from blead and another branch, by |
| 975 |
using the \f(CW\*(C`git cherry\-pick\*(C'\fR command. It is recommended to use the |
| 976 |
\&\fB\-x\fR option to \f(CW\*(C`git cherry\-pick\*(C'\fR in order to record the SHA1 of the |
| 977 |
original commit in the new commit message. |
| 978 |
.PP |
| 979 |
Before pushing any change to a maint version, make sure you've |
| 980 |
satisfied the steps in "Committing to blead" above. |
| 981 |
.SS "Using a smoke-me branch to test changes" |
| 982 |
.IX Subsection "Using a smoke-me branch to test changes" |
| 983 |
Sometimes a change affects code paths which you cannot test on the OSes |
| 984 |
which are directly available to you and it would be wise to have users |
| 985 |
on other OSes test the change before you commit it to blead. |
| 986 |
.PP |
| 987 |
Fortunately, there is a way to get your change smoke-tested on various |
| 988 |
OSes: push it to a "smoke-me" branch and wait for certain automated |
| 989 |
smoke-testers to report the results from their OSes. |
| 990 |
A "smoke-me" branch is identified by the branch name: specifically, as |
| 991 |
seen on github.com it must be a local branch whose first name |
| 992 |
component is precisely \f(CW\*(C`smoke\-me\*(C'\fR. |
| 993 |
.PP |
| 994 |
The procedure for doing this is roughly as follows (using the example of |
| 995 |
tonyc's smoke-me branch called win32stat): |
| 996 |
.PP |
| 997 |
First, make a local branch and switch to it: |
| 998 |
.PP |
| 999 |
.Vb 1 |
| 1000 |
\& % git checkout \-b win32stat |
| 1001 |
.Ve |
| 1002 |
.PP |
| 1003 |
Make some changes, build perl and test your changes, then commit them to |
| 1004 |
your local branch. Then push your local branch to a remote smoke-me |
| 1005 |
branch: |
| 1006 |
.PP |
| 1007 |
.Vb 1 |
| 1008 |
\& % git push origin win32stat:smoke\-me/tonyc/win32stat |
| 1009 |
.Ve |
| 1010 |
.PP |
| 1011 |
Now you can switch back to blead locally: |
| 1012 |
.PP |
| 1013 |
.Vb 1 |
| 1014 |
\& % git checkout blead |
| 1015 |
.Ve |
| 1016 |
.PP |
| 1017 |
and continue working on other things while you wait a day or two, |
| 1018 |
keeping an eye on the results reported for your \f(CW\*(C`smoke\-me\*(C'\fR branch at |
| 1019 |
<https://perl.develop\-help.com/?b=smoke\-me/tonyc/win32state>. |
| 1020 |
.PP |
| 1021 |
If all is well then update your blead branch: |
| 1022 |
.PP |
| 1023 |
.Vb 1 |
| 1024 |
\& % git pull |
| 1025 |
.Ve |
| 1026 |
.PP |
| 1027 |
then checkout your smoke-me branch once more and rebase it on blead: |
| 1028 |
.PP |
| 1029 |
.Vb 1 |
| 1030 |
\& % git rebase blead win32stat |
| 1031 |
.Ve |
| 1032 |
.PP |
| 1033 |
Now switch back to blead and merge your smoke-me branch into it: |
| 1034 |
.PP |
| 1035 |
.Vb 2 |
| 1036 |
\& % git checkout blead |
| 1037 |
\& % git merge win32stat |
| 1038 |
.Ve |
| 1039 |
.PP |
| 1040 |
As described earlier, if there are many changes on your smoke-me branch |
| 1041 |
then you should prepare a merge commit in which to give an overview of |
| 1042 |
those changes by using the following command instead of the last |
| 1043 |
command above: |
| 1044 |
.PP |
| 1045 |
.Vb 1 |
| 1046 |
\& % git merge win32stat \-\-no\-ff \-\-no\-commit |
| 1047 |
.Ve |
| 1048 |
.PP |
| 1049 |
You should now build perl and test your (merged) changes one last time |
| 1050 |
(ideally run the whole test suite, but failing that at least run the |
| 1051 |
\&\fIt/porting/*.t\fR tests) before pushing your changes as usual: |
| 1052 |
.PP |
| 1053 |
.Vb 1 |
| 1054 |
\& % git push origin blead |
| 1055 |
.Ve |
| 1056 |
.PP |
| 1057 |
Finally, you should then delete the remote smoke-me branch: |
| 1058 |
.PP |
| 1059 |
.Vb 1 |
| 1060 |
\& % git push origin :smoke\-me/tonyc/win32stat |
| 1061 |
.Ve |
| 1062 |
.PP |
| 1063 |
(which is likely to produce a warning like this, which can be ignored: |
| 1064 |
.PP |
| 1065 |
.Vb 4 |
| 1066 |
\& remote: fatal: ambiguous argument |
| 1067 |
\& \*(Aqrefs/heads/smoke\-me/tonyc/win32stat\*(Aq: |
| 1068 |
\& unknown revision or path not in the working tree. |
| 1069 |
\& remote: Use \*(Aq\-\-\*(Aq to separate paths from revisions |
| 1070 |
.Ve |
| 1071 |
.PP |
| 1072 |
) and then delete your local branch: |
| 1073 |
.PP |
| 1074 |
.Vb 1 |
| 1075 |
\& % git branch \-d win32stat |
| 1076 |
.Ve |