{ "mode": "man", "parameter": "PERLGIT", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/PERLGIT/1/json", "generated": "2026-07-05T13:20:06Z", "sections": { "NAME": { "content": "perlgit - Detailed information about git and the Perl repository\n", "subsections": [] }, "DESCRIPTION": { "content": "This document provides details on using git to develop Perl. If you are just interested in\nworking on a quick patch, see perlhack first. This document is intended for people who are\nregular contributors to Perl, including those with write access to the git repository.\n", "subsections": [] }, "CLONING THE REPOSITORY": { "content": "All of Perl's source code is kept centrally in a Git repository at github.com.\n\nYou can make a read-only clone of the repository by running:\n\n% git clone git://github.com/Perl/perl5.git perl\n\nThis uses the git protocol (port 9418).\n\nIf you cannot use the git protocol for firewall reasons, you can also clone via http:\n\n% git clone https://github.com/Perl/perl5.git perl\n", "subsections": [] }, "WORKING WITH THE REPOSITORY": { "content": "Once you have changed into the repository directory, you can inspect it. After a clone the\nrepository will contain a single local branch, which will be the current branch as well, as\nindicated by the asterisk.\n\n% git branch\n* blead\n\nUsing the -a switch to \"branch\" will also show the remote tracking branches in the\nrepository:\n\n% git branch -a\n* blead\norigin/HEAD\norigin/blead\n...\n\nThe branches that begin with \"origin\" correspond to the \"git remote\" that you cloned from\n(which is named \"origin\"). Each branch on the remote will be exactly tracked by these\nbranches. You should NEVER do work on these remote tracking branches. You only ever do work\nin a local branch. Local branches can be configured to automerge (on pull) from a designated\nremote tracking branch. This is the case with the default branch \"blead\" which will be\nconfigured to merge from the remote tracking branch \"origin/blead\".\n\nYou can see recent commits:\n\n% git log\n\nAnd pull new changes from the repository, and update your local repository (must be clean\nfirst)\n\n% git pull\n\nAssuming we are on the branch \"blead\" immediately after a pull, this command would be more or\nless equivalent to:\n\n% git fetch\n% git merge origin/blead\n\nIn fact if you want to update your local repository without touching your working directory\nyou do:\n\n% git fetch\n\nAnd if you want to update your remote-tracking branches for all defined remotes\nsimultaneously you can do\n\n% git remote update\n\nNeither of these last two commands will update your working directory, however both will\nupdate the remote-tracking branches in your repository.\n\nTo make a local branch of a remote branch:\n\n% git checkout -b maint-5.10 origin/maint-5.10\n\nTo switch back to blead:\n\n% git checkout blead\n", "subsections": [ { "name": "Finding out your status", "content": "The most common git command you will use will probably be\n\n% git status\n\nThis command will produce as output a description of the current state of the repository,\nincluding modified files and unignored untracked files, and in addition it will show things\nlike what files have been staged for the next commit, and usually some useful information\nabout how to change things. For instance the following:\n\n% git status\nOn branch blead\nYour branch is ahead of 'origin/blead' by 1 commit.\n\nChanges to be committed:\n(use \"git reset HEAD ...\" to unstage)\n\nmodified: pod/perlgit.pod\n\nChanges not staged for commit:\n(use \"git add ...\" to update what will be committed)\n(use \"git checkout -- ...\" to discard changes in working\ndirectory)\n\nmodified: pod/perlgit.pod\n\nUntracked files:\n(use \"git add ...\" to include in what will be committed)\n\ndeliberate.untracked\n\nThis shows that there were changes to this document staged for commit, and that there were\nfurther changes in the working directory not yet staged. It also shows that there was an\nuntracked file in the working directory, and as you can see shows how to change all of this.\nIt also shows that there is one commit on the working branch \"blead\" which has not been\npushed to the \"origin\" remote yet. NOTE: This output is also what you see as a template if\nyou do not provide a message to \"git commit\".\n" }, { "name": "Patch workflow", "content": "First, please read perlhack for details on hacking the Perl core. That document covers many\ndetails on how to create a good patch.\n\nIf you already have a Perl repository, you should ensure that you're on the blead branch, and\nyour repository is up to date:\n\n% git checkout blead\n% git pull\n\nIt's preferable to patch against the latest blead version, since this is where new\ndevelopment occurs for all changes other than critical bug fixes. Critical bug fix patches\nshould be made against the relevant maint branches, or should be submitted with a note\nindicating all the branches where the fix should be applied.\n\nNow that we have everything up to date, we need to create a temporary new branch for these\nchanges and switch into it:\n\n% git checkout -b orange\n\nwhich is the short form of\n\n% git branch orange\n% git checkout orange\n\nCreating a topic branch makes it easier for the maintainers to rebase or merge back into the\nmaster blead for a more linear history. If you don't work on a topic branch the maintainer\nhas to manually cherry pick your changes onto blead before they can be applied.\n\nThat'll get you scolded on perl5-porters, so don't do that. Be Awesome.\n\nThen make your changes. For example, if Leon Brocard changes his name to Orange Brocard, we\nshould change his name in the AUTHORS file:\n\n% perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS\n\nYou can see what files are changed:\n\n% git status\nOn branch orange\nChanges to be committed:\n(use \"git reset HEAD ...\" to unstage)\n\nmodified: AUTHORS\n\nAnd you can see the changes:\n\n% git diff\ndiff --git a/AUTHORS b/AUTHORS\nindex 293dd70..722c93e 100644\n--- a/AUTHORS\n+++ b/AUTHORS\n@@ -541,7 +541,7 @@ Lars Hecking \nLaszlo Molnar \nLeif Huhn \nLen Johnson \n-Leon Brocard \n+Orange Brocard \nLes Peters \nLesley Binks \nLincoln D. Stein \n\nNow commit your change locally:\n\n% git commit -a -m 'Rename Leon Brocard to Orange Brocard'\nCreated commit 6196c1d: Rename Leon Brocard to Orange Brocard\n1 files changed, 1 insertions(+), 1 deletions(-)\n\nThe \"-a\" option is used to include all files that git tracks that you have changed. If at\nthis time, you only want to commit some of the files you have worked on, you can omit the\n\"-a\" and use the command \"git add FILE ...\" before doing the commit. \"git add --interactive\"\nallows you to even just commit portions of files instead of all the changes in them.\n\nThe \"-m\" option is used to specify the commit message. If you omit it, git will open a text\neditor for you to compose the message interactively. This is useful when the changes are more\ncomplex than the sample given here, and, depending on the editor, to know that the first line\nof the commit message doesn't exceed the 50 character legal maximum. See \"Commit message\" in\nperlhack for more information about what makes a good commit message.\n\nOnce you've finished writing your commit message and exited your editor, git will write your\nchange to disk and tell you something like this:\n\nCreated commit daf8e63: explain git status and stuff about remotes\n1 files changed, 83 insertions(+), 3 deletions(-)\n\nIf you re-run \"git status\", you should see something like this:\n\n% git status\nOn branch orange\nUntracked files:\n(use \"git add ...\" to include in what will be committed)\n\ndeliberate.untracked\n\nnothing added to commit but untracked files present (use \"git add\" to\ntrack)\n\nWhen in doubt, before you do anything else, check your status and read it carefully, many\nquestions are answered directly by the git status output.\n\nYou can examine your last commit with:\n\n% git show HEAD\n\nand if you are not happy with either the description or the patch itself you can fix it up by\nediting the files once more and then issue:\n\n% git commit -a --amend\n\nNow, create a fork on GitHub to push your branch to, and add it as a remote if you haven't\nalready, as described in the GitHub documentation at\n:\n\n% git remote add fork git@github.com:MyUser/perl5.git\n\nAnd push the branch to your fork:\n\n% git push -u fork orange\n\nYou should now submit a Pull Request (PR) on GitHub from the new branch to blead. For more\ninformation, see the GitHub documentation at\n.\n\nYou can also send patch files to perl5-porters@perl.org \ndirectly if the patch is not ready to be applied, but intended for discussion.\n\nTo create a patch file for all your local changes:\n\n% git format-patch -M blead..\n0001-Rename-Leon-Brocard-to-Orange-Brocard.patch\n\nOr for a lot of changes, e.g. from a topic branch:\n\n% git format-patch --stdout -M blead.. > topic-branch-changes.patch\n\nIf you want to delete your temporary branch, you may do so with:\n\n% git checkout blead\n% git branch -d orange\nerror: The branch 'orange' is not an ancestor of your current HEAD.\nIf you are sure you want to delete it, run 'git branch -D orange'.\n% git branch -D orange\nDeleted branch orange.\n" }, { "name": "A note on derived files", "content": "Be aware that many files in the distribution are derivative--avoid patching them, because git\nwon't see the changes to them, and the build process will overwrite them. Patch the originals\ninstead. Most utilities (like perldoc) are in this category, i.e. patch utils/perldoc.PL\nrather than utils/perldoc. Similarly, don't create patches for files under $srcroot/ext from\ntheir copies found in $installroot/lib. If you are unsure about the proper location of a\nfile that may have gotten copied while building the source distribution, consult the\nMANIFEST.\n" }, { "name": "Cleaning a working directory", "content": "The command \"git clean\" can with varying arguments be used as a replacement for \"make clean\".\n\nTo reset your working directory to a pristine condition you can do:\n\n% git clean -dxf\n\nHowever, be aware this will delete ALL untracked content. You can use\n\n% git clean -Xf\n\nto remove all ignored untracked files, such as build and test byproduct, but leave any\nmanually created files alone.\n\nIf you only want to cancel some uncommitted edits, you can use \"git checkout\" and give it a\nlist of files to be reverted, or \"git checkout -f\" to revert them all.\n\nIf you want to cancel one or several commits, you can use \"git reset\".\n" }, { "name": "Bisecting", "content": "\"git\" provides a built-in way to determine which commit should be blamed for introducing a\ngiven bug. \"git bisect\" performs a binary search of history to locate the first failing\ncommit. It is fast, powerful and flexible, but requires some setup and to automate the\nprocess an auxiliary shell script is needed.\n\nThe core provides a wrapper program, Porting/bisect.pl, which attempts to simplify as much as\npossible, making bisecting as simple as running a Perl one-liner. For example, if you want to\nknow when this became an error:\n\nperl -e 'my $a := 2'\n\nyou simply run this:\n\n.../Porting/bisect.pl -e 'my $a := 2;'\n\nUsing Porting/bisect.pl, with one command (and no other files) it's easy to find out\n\n• Which commit caused this example code to break?\n\n• Which commit caused this example code to start working?\n\n• Which commit added the first file to match this regex?\n\n• Which commit removed the last file to match this regex?\n\nusually without needing to know which versions of perl to use as start and end revisions, as\nPorting/bisect.pl automatically searches to find the earliest stable version for which the\ntest case passes. Run \"Porting/bisect.pl --help\" for the full documentation, including how to\nset the \"Configure\" and build time options.\n\nIf you require more flexibility than Porting/bisect.pl has to offer, you'll need to run \"git\nbisect\" yourself. It's most useful to use \"git bisect run\" to automate the building and\ntesting of perl revisions. For this you'll need a shell script for \"git\" to call to test a\nparticular revision. An example script is Porting/bisect-example.sh, which you should copy\noutside of the repository, as the bisect process will reset the state to a clean checkout as\nit runs. The instructions below assume that you copied it as ~/run and then edited it as\nappropriate.\n\nYou first enter in bisect mode with:\n\n% git bisect start\n\nFor example, if the bug is present on \"HEAD\" but wasn't in 5.10.0, \"git\" will learn about\nthis when you enter:\n\n% git bisect bad\n% git bisect good perl-5.10.0\nBisecting: 853 revisions left to test after this\n\nThis results in checking out the median commit between \"HEAD\" and \"perl-5.10.0\". You can then\nrun the bisecting process with:\n\n% git bisect run ~/run\n\nWhen the first bad commit is isolated, \"git bisect\" will tell you so:\n\nca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit\ncommit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5\nAuthor: Dave Mitchell \nDate: Sat Feb 9 14:56:23 2008 +0000\n\n[perl #49472] Attributes + Unknown Error\n...\n\nbisect run success\n\nYou can peek into the bisecting process with \"git bisect log\" and \"git bisect visualize\".\n\"git bisect reset\" will get you out of bisect mode.\n\nPlease note that the first \"good\" state must be an ancestor of the first \"bad\" state. If you\nwant to search for the commit that solved some bug, you have to negate your test case (i.e.\nexit with 1 if OK and 0 if not) and still mark the lower bound as \"good\" and the upper as\n\"bad\". The \"first bad commit\" has then to be understood as the \"first commit where the bug is\nsolved\".\n\n\"git help bisect\" has much more information on how you can tweak your binary searches.\n\nFollowing bisection you may wish to configure, build and test perl at commits identified by\nthe bisection process. Sometimes, particularly with older perls, \"make\" may fail during this\nprocess. In this case you may be able to patch the source code at the older commit point.\nTo do so, please follow the suggestions provided in \"Building perl at older commits\" in\nperlhack.\n" }, { "name": "Topic branches and rewriting history", "content": "Individual committers should create topic branches under yourname/somedescriptivename:\n\n% branch=\"$yourname/$somedescriptivename\"\n% git checkout -b $branch\n... do local edits, commits etc ...\n% git push origin -u $branch\n\nShould you be stuck with an ancient version of git (prior to 1.7), then \"git push\" will not\nhave the \"-u\" switch, and you have to replace the last step with the following sequence:\n\n% git push origin $branch:refs/heads/$branch\n% git config branch.$branch.remote origin\n% git config branch.$branch.merge refs/heads/$branch\n\nIf you want to make changes to someone else's topic branch, you should check with its creator\nbefore making any change to it.\n\nYou might sometimes find that the original author has edited the branch's history. There are\nlots of good reasons for this. Sometimes, an author might simply be rebasing the branch onto\na newer source point. Sometimes, an author might have found an error in an early commit\nwhich they wanted to fix before merging the branch to blead.\n\nCurrently the master repository is configured to forbid non-fast-forward merges. This means\nthat the branches within can not be rebased and pushed as a single step.\n\nThe only way you will ever be allowed to rebase or modify the history of a pushed branch is\nto delete it and push it as a new branch under the same name. Please think carefully about\ndoing this. It may be better to sequentially rename your branches so that it is easier for\nothers working with you to cherry-pick their local changes onto the new version. (XXX: needs\nexplanation).\n\nIf you want to rebase a personal topic branch, you will have to delete your existing topic\nbranch and push as a new version of it. You can do this via the following formula (see the\nexplanation about \"refspec\"'s in the git push documentation for details) after you have\nrebased your branch:\n\n# first rebase\n% git checkout $user/$topic\n% git fetch\n% git rebase origin/blead\n\n# then \"delete-and-push\"\n% git push origin :$user/$topic\n% git push origin $user/$topic\n\nNOTE: it is forbidden at the repository level to delete any of the \"primary\" branches. That\nis any branch matching \"m!^(blead|maint|perl)!\". Any attempt to do so will result in git\nproducing an error like this:\n\n% git push origin :blead\n* It is forbidden to delete blead/maint branches in this repository\nerror: hooks/update exited with error code 1\nerror: hook declined to update refs/heads/blead\nTo ssh://perl5.git.perl.org/perl\n! [remote rejected] blead (hook declined)\nerror: failed to push some refs to 'ssh://perl5.git.perl.org/perl'\n\nAs a matter of policy we do not edit the history of the blead and maint-* branches. If a typo\n(or worse) sneaks into a commit to blead or maint-*, we'll fix it in another commit. The only\ntypes of updates allowed on these branches are \"fast-forwards\", where all history is\npreserved.\n\nAnnotated tags in the canonical perl.git repository will never be deleted or modified. Think\nlong and hard about whether you want to push a local tag to perl.git before doing so.\n(Pushing simple tags is not allowed.)\n" }, { "name": "Grafts", "content": "The perl history contains one mistake which was not caught in the conversion: a merge was\nrecorded in the history between blead and maint-5.10 where no merge actually occurred. Due to\nthe nature of git, this is now impossible to fix in the public repository. You can remove\nthis mis-merge locally by adding the following line to your \".git/info/grafts\" file:\n\n296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930\n\nIt is particularly important to have this graft line if any bisecting is done in the area of\nthe \"merge\" in question.\n" } ] }, "WRITE ACCESS TO THE GIT REPOSITORY": { "content": "Once you have write access, you will need to modify the URL for the origin remote to enable\npushing. Edit .git/config with the git-config(1) command:\n\n% git config remote.origin.url git@github.com:Perl/perl5.git\n\nYou can also set up your user name and e-mail address. Most people do this once globally in\ntheir ~/.gitconfig by doing something like:\n\n% git config --global user.name \"Ævar Arnfjörð Bjarmason\"\n% git config --global user.email avarab@gmail.com\n\nHowever, if you'd like to override that just for perl, execute something like the following\nin perl:\n\n% git config user.email avar@cpan.org\n\nIt is also possible to keep \"origin\" as a git remote, and add a new remote for ssh access:\n\n% git remote add camel git@github.com:Perl/perl5.git\n\nThis allows you to update your local repository by pulling from \"origin\", which is faster and\ndoesn't require you to authenticate, and to push your changes back with the \"camel\" remote:\n\n% git fetch camel\n% git push camel\n\nThe \"fetch\" command just updates the \"camel\" refs, as the objects themselves should have been\nfetched when pulling from \"origin\".\n", "subsections": [ { "name": "Working with Github pull requests", "content": "Pull requests typically originate from outside of the \"Perl/perl.git\" repository, so if you\nwant to test or work with it locally a vanilla \"git fetch\" from the \"Perl/perl5.git\"\nrepository won't fetch it.\n\nHowever Github does provide a mechanism to fetch a pull request to a local branch. They are\navailable on Github remotes under \"pull/\", so you can use \"git fetch\npull/PRID/head:localname\" to make a local copy. eg. to fetch pull request 9999 to the local\nbranch \"local-branch-name\" run:\n\ngit fetch origin pull/9999/head:local-branch-name\n\nand then:\n\ngit checkout local-branch-name\n\nNote: this branch is not rebased on \"blead\", so instead of the checkout above, you might\nwant:\n\ngit rebase origin/blead local-branch-name\n\nwhich rebases \"local-branch-name\" on \"blead\", and checks it out.\n\nAlternatively you can configure the remote to fetch all pull requests as remote-tracking\nbranches. To do this edit the remote in .git/config, for example if your github remote is\n\"origin\" you'd have:\n\n[remote \"origin\"]\nurl = git@github.com:/Perl/perl5.git\nfetch = +refs/heads/*:refs/remotes/origin/*\n\nAdd a line to map the remote pull request branches to remote-tracking branches:\n\n[remote \"origin\"]\nurl = git@github.com:/Perl/perl5.git\nfetch = +refs/heads/*:refs/remotes/origin/*\nfetch = +refs/pull/*/head:refs/remotes/origin/pull/*\n\nand then do a fetch as normal:\n\ngit fetch origin\n\nThis will create a remote-tracking branch for every pull request, including closed requests.\n\nTo remove those remote-tracking branches, remove the line added above and prune:\n\ngit fetch -p origin # or git remote prune origin\n" }, { "name": "Accepting a patch", "content": "If you have received a patch file generated using the above section, you should try out the\npatch.\n\nFirst we need to create a temporary new branch for these changes and switch into it:\n\n% git checkout -b experimental\n\nPatches that were formatted by \"git format-patch\" are applied with \"git am\":\n\n% git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch\nApplying Rename Leon Brocard to Orange Brocard\n\nNote that some UNIX mail systems can mess with text attachments containing 'From '. This will\nfix them up:\n\n% perl -pi -e's/^>From /From /' \\\n0001-Rename-Leon-Brocard-to-Orange-Brocard.patch\n\nIf just a raw diff is provided, it is also possible use this two-step process:\n\n% git apply bugfix.diff\n% git commit -a -m \"Some fixing\" \\\n--author=\"That Guy \"\n\nNow we can inspect the change:\n\n% git show HEAD\ncommit b1b3dab48344cff6de4087efca3dbd63548ab5e2\nAuthor: Leon Brocard \nDate: Fri Dec 19 17:02:59 2008 +0000\n\nRename Leon Brocard to Orange Brocard\n\ndiff --git a/AUTHORS b/AUTHORS\nindex 293dd70..722c93e 100644\n--- a/AUTHORS\n+++ b/AUTHORS\n@@ -541,7 +541,7 @@ Lars Hecking \nLaszlo Molnar \nLeif Huhn \nLen Johnson \n-Leon Brocard \n+Orange Brocard \nLes Peters \nLesley Binks \nLincoln D. Stein \n\nIf you are a committer to Perl and you think the patch is good, you can then merge it into\nblead then push it out to the main repository:\n\n% git checkout blead\n% git merge experimental\n% git push origin blead\n\nIf you want to delete your temporary branch, you may do so with:\n\n% git checkout blead\n% git branch -d experimental\nerror: The branch 'experimental' is not an ancestor of your current\nHEAD. If you are sure you want to delete it, run 'git branch -D\nexperimental'.\n% git branch -D experimental\nDeleted branch experimental.\n" }, { "name": "Committing to blead", "content": "The 'blead' branch will become the next production release of Perl.\n\nBefore pushing any local change to blead, it's incredibly important that you do a few things,\nlest other committers come after you with pitchforks and torches:\n\n• Make sure you have a good commit message. See \"Commit message\" in perlhack for details.\n\n• Run the test suite. You might not think that one typo fix would break a test file. You'd\nbe wrong. Here's an example of where not running the suite caused problems. A patch was\nsubmitted that added a couple of tests to an existing .t. It couldn't possibly affect\nanything else, so no need to test beyond the single affected .t, right? But, the\nsubmitter's email address had changed since the last of their submissions, and this\ncaused other tests to fail. Running the test target given in the next item would have\ncaught this problem.\n\n• If you don't run the full test suite, at least \"make testporting\". This will run basic\nsanity checks. To see which sanity checks, have a look in t/porting.\n\n• If you make any changes that affect miniperl or core routines that have different code\npaths for miniperl, be sure to run \"make minitest\". This will catch problems that even\nthe full test suite will not catch because it runs a subset of tests under miniperl\nrather than perl.\n" }, { "name": "On merging and rebasing", "content": "Simple, one-off commits pushed to the 'blead' branch should be simple commits that apply\ncleanly. In other words, you should make sure your work is committed against the current\nposition of blead, so that you can push back to the master repository without merging.\n\nSometimes, blead will move while you're building or testing your changes. When this happens,\nyour push will be rejected with a message like this:\n\nTo ssh://perl5.git.perl.org/perl.git\n! [rejected] blead -> blead (non-fast-forward)\nerror: failed to push some refs to 'ssh://perl5.git.perl.org/perl.git'\nTo prevent you from losing history, non-fast-forward updates were\nrejected Merge the remote changes (e.g. 'git pull') before pushing\nagain. See the 'Note about fast-forwards' section of 'git push --help'\nfor details.\n\nWhen this happens, you can just rebase your work against the new position of blead, like this\n(assuming your remote for the master repository is \"p5p\"):\n\n% git fetch p5p\n% git rebase p5p/blead\n\nYou will see your commits being re-applied, and you will then be able to push safely. More\ninformation about rebasing can be found in the documentation for the git-rebase(1) command.\n\nFor larger sets of commits that only make sense together, or that would benefit from a\nsummary of the set's purpose, you should use a merge commit. You should perform your work on\na topic branch, which you should regularly rebase against blead to ensure that your code is\nnot broken by blead moving. When you have finished your work, please perform a final rebase\nand test. Linear history is something that gets lost with every commit on blead, but a final\nrebase makes the history linear again, making it easier for future maintainers to see what\nhas happened. Rebase as follows (assuming your work was on the branch \"committer/somework\"):\n\n% git checkout committer/somework\n% git rebase blead\n\nThen you can merge it into master like this:\n\n% git checkout blead\n% git merge --no-ff --no-commit committer/somework\n% git commit -a\n\nThe switches above deserve explanation. \"--no-ff\" indicates that even if all your work can\nbe applied linearly against blead, a merge commit should still be prepared. This ensures\nthat all your work will be shown as a side branch, with all its commits merged into the\nmainstream blead by the merge commit.\n\n\"--no-commit\" means that the merge commit will be prepared but not committed. The commit is\nthen actually performed when you run the next command, which will bring up your editor to\ndescribe the commit. Without \"--no-commit\", the commit would be made with nearly no useful\nmessage, which would greatly diminish the value of the merge commit as a placeholder for the\nwork's description.\n\nWhen describing the merge commit, explain the purpose of the branch, and keep in mind that\nthis description will probably be used by the eventual release engineer when reviewing the\nnext perldelta document.\n" }, { "name": "Committing to maintenance versions", "content": "Maintenance versions should only be altered to add critical bug fixes, see perlpolicy.\n\nTo commit to a maintenance version of perl, you need to create a local tracking branch:\n\n% git checkout --track -b maint-5.005 origin/maint-5.005\n\nThis creates a local branch named \"maint-5.005\", which tracks the remote branch\n\"origin/maint-5.005\". Then you can pull, commit, merge and push as before.\n\nYou can also cherry-pick commits from blead and another branch, by using the \"git\ncherry-pick\" command. It is recommended to use the -x option to \"git cherry-pick\" in order to\nrecord the SHA1 of the original commit in the new commit message.\n\nBefore pushing any change to a maint version, make sure you've satisfied the steps in\n\"Committing to blead\" above.\n" }, { "name": "Using a smoke-me branch to test changes", "content": "Sometimes a change affects code paths which you cannot test on the OSes which are directly\navailable to you and it would be wise to have users on other OSes test the change before you\ncommit it to blead.\n\nFortunately, there is a way to get your change smoke-tested on various OSes: push it to a\n\"smoke-me\" branch and wait for certain automated smoke-testers to report the results from\ntheir OSes. A \"smoke-me\" branch is identified by the branch name: specifically, as seen on\ngithub.com it must be a local branch whose first name component is precisely \"smoke-me\".\n\nThe procedure for doing this is roughly as follows (using the example of tonyc's smoke-me\nbranch called win32stat):\n\nFirst, make a local branch and switch to it:\n\n% git checkout -b win32stat\n\nMake some changes, build perl and test your changes, then commit them to your local branch.\nThen push your local branch to a remote smoke-me branch:\n\n% git push origin win32stat:smoke-me/tonyc/win32stat\n\nNow you can switch back to blead locally:\n\n% git checkout blead\n\nand continue working on other things while you wait a day or two, keeping an eye on the\nresults reported for your smoke-me branch at\n.\n\nIf all is well then update your blead branch:\n\n% git pull\n\nthen checkout your smoke-me branch once more and rebase it on blead:\n\n% git rebase blead win32stat\n\nNow switch back to blead and merge your smoke-me branch into it:\n\n% git checkout blead\n% git merge win32stat\n\nAs described earlier, if there are many changes on your smoke-me branch then you should\nprepare a merge commit in which to give an overview of those changes by using the following\ncommand instead of the last command above:\n\n% git merge win32stat --no-ff --no-commit\n\nYou should now build perl and test your (merged) changes one last time (ideally run the whole\ntest suite, but failing that at least run the t/porting/*.t tests) before pushing your\nchanges as usual:\n\n% git push origin blead\n\nFinally, you should then delete the remote smoke-me branch:\n\n% git push origin :smoke-me/tonyc/win32stat\n\n(which is likely to produce a warning like this, which can be ignored:\n\nremote: fatal: ambiguous argument\n'refs/heads/smoke-me/tonyc/win32stat':\nunknown revision or path not in the working tree.\nremote: Use '--' to separate paths from revisions\n\n) and then delete your local branch:\n\n% git branch -d win32stat\n\n\n\nperl v5.34.0 2026-06-23 PERLGIT(1)" } ] } }, "summary": "perlgit - Detailed information about git and the Perl repository", "flags": [], "examples": [], "see_also": [] }