Build a Safe Perl Core Patch Branch with perlgit

You will finish with a local Perl source checkout, a current blead branch, and a separate topic branch ready for one focused change. The workflow also shows how to inspect what Git will commit and how to get back out of a branch or bisect session. Allow 15 minutes for the repository setup, plus however long the Perl test suite takes on your machine.

This guide follows the installed perlgit manual from Perl 5.38.2, supplied by perl-doc 5.38.2-3.2ubuntu0.6. Its examples use the Perl GitHub repository and the branch name used by that documentation. You need Git, network access for the clone, and enough disk space for a Perl source tree. No command below needs sudo.

1. Clone the Perl repository

Choose a directory where a new perl folder is safe to create. HTTPS is the simpler read-only choice when SSH authentication is not configured:

$ git clone https://github.com/Perl/perl5.git perl
$ cd perl
$ git branch
* blead

The SSH form in the manual is [email protected]:Perl/perl5.git. A clone normally creates local blead and remote-tracking branches such as origin/blead. Work on the local branch. Do not edit a remote-tracking name such as origin/blead.

Checkpoint: confirm the checkout and its remote before editing anything:

$ git status --short --branch
## blead...origin/blead
$ git remote -v
origin  https://github.com/Perl/perl5.git (fetch)
origin  https://github.com/Perl/perl5.git (push)

The exact status line can differ if the remote or Git version adds tracking details. The useful result is a clean working tree on local blead.

2. Update blead only while it is clean

Before pulling, read the status output. An existing edit, staged change or untracked file needs its own decision. Save it elsewhere, commit it on the correct branch, or leave it alone. Do not use a pull to hide unrelated work.

$ git status
$ git pull

git pull combines fetching with updating the current working branch. The manual describes the equivalent shape as git fetch followed by git merge origin/blead. If you only want new remote-tracking information without changing files, use:

$ git fetch
$ git status --short --branch

If the pull reports conflicts, stop and inspect them rather than creating a patch on top of an unresolved merge. If you need to abandon an in-progress merge, use the Git command shown by git status, commonly git merge --abort, after checking that it will not discard work you meant to keep.

3. Create a topic branch before making the change

Give the branch a short, descriptive name. The older spelling in the manual is git checkout -b; it remains useful for this workflow:

$ git checkout -b yourname/documentation-fix
Switched to a new branch 'yourname/documentation-fix'
$ git branch --show-current
yourname/documentation-fix

Replace yourname and the topic with values that identify your work. The topic branch keeps your edits separate from blead, which makes review, rebase and recovery easier. Make one coherent change, then run the relevant tests described by the Perl development documentation.

Checkpoint: after editing, inspect both the file list and the actual patch:

$ git status
$ git diff
$ git diff --check

git diff shows unstaged edits. If you stage a file, use git diff --cached to inspect what the next commit will contain. Do not rely on a clean-looking editor buffer: status and diff are the source of truth.

4. Commit only the intended files

For a small change to tracked files, the documented shortcut is:

$ git commit -a -m 'Describe the focused change'
$ git show HEAD
$ git status

The -a option includes changed tracked files, but it does not add new untracked files. For selective staging, name the files explicitly:

$ git add path/to/file path/to/test.t
$ git diff --cached
$ git commit -m 'Describe the focused change'

Read the cached diff before committing. This catches generated files, debug output and unrelated edits. After the commit, git show HEAD displays the commit and patch; git status should show no unintended changes.

5. Publish a branch or produce a patch

If you have a GitHub fork, add it as a separate remote and push the topic branch:

$ git remote add fork [email protected]:YOUR_GITHUB_USER/perl5.git
$ git push -u fork yourname/documentation-fix

Replace YOUR_GITHUB_USER and the branch name. The -u option records the upstream so later pushes can be shorter. Open the pull request from that branch to blead in the hosting service. If the change is not ready for a pull request, create a mail-ready patch instead:

$ git format-patch -M blead..
0001-description-of-change.patch

The filename and commit subject are generated from your commit, so do not script against that exact name. Keep the original repository and branch until the patch has been checked by its recipient.

6. Recover without throwing work away

To amend the latest local commit, edit the files, inspect the result, then run:

$ git add path/to/file
$ git commit --amend
$ git show HEAD

Amending changes the commit identity. Do not amend a commit that other people already rely on without agreeing how to replace the remote history.

To return to blead and remove a topic branch after its work is merged:

$ git checkout blead
$ git branch -d yourname/documentation-fix

If Git refuses because commits are not merged, stop and inspect git log --oneline --decorate --graph --all. The manual shows git branch -D as the forceful alternative. It deletes the branch reference, so use it only after confirming that the commits exist elsewhere or are no longer needed. A deleted local branch is not a substitute for a backup.

7. Bisect a regression when the first bad commit is unclear

Perl includes Porting/bisect.pl, a wrapper around Git bisect. For a reproducible command that fails in the current tree, run the wrapper from the repository:

$ Porting/bisect.pl -e 'my $a := 2;'
$ git bisect reset

Read Porting/bisect.pl --help before using a more complex test. The process checks out many revisions, so keep the test script outside the repository and do not leave valuable uncommitted edits in the tree. If you use raw Git bisect, the core sequence is git bisect start, mark the current revision with git bisect bad, mark a known-good ancestor with git bisect good REVISION, and finish with git bisect reset. That final command returns you to the branch you had before bisection.