Find Your Way Around the Perl Source Repository

You will finish with a local, read-only checkout of Perl's source, a safe way to inspect the current development branch, and a small- change workflow that keeps your edits separate from upstream updates. The commands below match the installed Perl 5.38.2 documentation from the perl-doc package, version 5.38.2-3.2ubuntu0.6.

Allow about 20 minutes for the checkout and initial inspection. You need Git, network access to GitHub, and enough disk space for a complete Perl history. You do not need root privileges for any step. The repository is source code, not a package installation, so this guide does not install or replace your system Perl.

1. Check the tools you will use

Confirm that Git and Perl are visible before you create a directory. This is an ordinary read-only check:

$ git --version
git version 2.43.0
$ perl -v | sed -n '1,4p'
This is perl 5, version 38, subversion 2 ...

Your version strings may differ. The important distinction is that the installed manuals describe Perl 5.38.2 here, while the checkout you are about to make follows the repository's current blead branch.

2. Clone the official repository

Choose a parent directory you own, then clone the official Perl repository into a new directory named perl5:

$ mkdir -p "$HOME/src"
$ cd "$HOME/src"
$ git clone https://github.com/Perl/perl5.git perl5
Cloning into 'perl5'...
...

The HTTPS URL is the practical fallback documented for environments where the Git protocol or SSH is unavailable. The clone includes the history needed to inspect older revisions, not just the latest files. If perl5 already exists, stop and inspect it rather than allowing Git to merge two unrelated checkouts.

Verify the remote and the branch without changing anything:

$ cd "$HOME/src/perl5"
$ git remote -v
origin  https://github.com/Perl/perl5.git (fetch)
origin  https://github.com/Perl/perl5.git (push)
$ git branch --show-current
blead

3. Read the repository map before editing

The short perlrepository manual is an index, not a complete Git tutorial. It points to perlhack for the development process and perlgit for repository details. Read those copies from the checkout when you need advice that tracks the source you are examining:

$ perldoc pod/perlrepository.pod
$ perldoc pod/perlhack.pod
$ perldoc pod/perlgit.pod

For a quick orientation, list the top-level files and the documentation directory:

$ printf '%s\n' 'Top level:'
$ find . -maxdepth 1 -mindepth 1 -printf '%f\n' | sort | sed -n '1,20p'
$ printf '%s\n' 'Selected manuals:'
$ find pod -maxdepth 1 -type f -name 'perl*.pod' | sort | sed -n '1,20p'

Do not assume that a manual's installed copy and the checkout describe precisely the same revision. The checkout is the useful authority for work on that checkout; the system copy remains a record of the version installed on this machine.

4. Update only a clean working tree

Before fetching new upstream history, check whether you have local work:

$ git status --short
$ git log -1 --oneline
<commit-id> <latest commit subject>

An empty first command means there are no modified or untracked files. If it prints anything, stop. Save your work in a topic branch or another safe copy before updating. A pull can combine upstream commits with local commits, but it cannot protect edits that you have not recorded.

With a clean tree, update the remote-tracking data and then the working branch:

$ git fetch origin
$ git pull --ff-only
Already up to date.

git fetch updates Git's view of the remote without changing your files. The --ff-only guard makes pull refuse a merge when the histories have diverged, leaving you in control of the next decision. If it refuses, inspect git log --oneline --graph --decorate --all -20 and read the current perlgit advice before choosing a merge or rebase.

5. Make a small change on a topic branch

Create a branch before editing. Use a name that describes the task:

$ git switch -c fix-documentation-typo
Switched to a new branch 'fix-documentation-typo'

Now edit the relevant file, then review both the file list and the patch:

$ git status --short
$ git diff --check
$ git diff -- pod/perlrepository.pod

git diff --check catches common whitespace mistakes; it does not prove that the documentation is correct. Run the tests appropriate to the change. For a core build, the installed guide documents this starting point:

$ ./Configure -des -Dusedevel
$ make test

Building Perl can take time and writes generated files in the checkout. Do not run it merely to inspect a manual. Keep the test output if you are preparing a report.

6. Save the work and prepare it for review

When the diff and tests are satisfactory, commit the tracked changes with a single-sentence message:

$ git add pod/perlrepository.pod
$ git diff --cached --check
$ git commit -m 'Clarify the repository guide'
[fix-documentation-typo <commit-id>] Clarify the repository guide

Stage named files rather than using a broad command when the checkout may contain generated or unrelated files. Before any push, inspect git status and git log -1 --stat. Pushing changes is an external action: send only your topic branch to a fork or remote you control, and do not push directly to the Perl project unless you have explicit maintainer authority.

To abandon an uncommitted experiment, first confirm the exact paths with git status --short. git restore -- path/to/file discards those working-tree edits and is irreversible. To leave the branch but keep its commit, switch back with git switch blead; your topic branch remains available.