Git Setup

These steps will walk you through your basic Git setup when working with TYPO3.

git clone

Create a directory for your TYPO3 core installation and change into it, e.g.:

shell command
mkdir /var/www/t3coredev
cd /var/www/t3coredev
Copied!

Clone the TYPO3 CMS core repository:

Use the SSH clone method if you've added your SSH key to your GitHub account:

shell command
git clone git@github.com:typo3/typo3 .
Copied!

As an alternative, you can always use the HTTPS clone method:

shell command
git clone https://github.com/typo3/typo3.git .
Copied!

Set Username and Email

-- required (unless this is already setup globally, see git config --global -l)

You need to instruct git to work with your name and email address. Make sure the email address and user name are the same as those you used when setting up your TYPO3 account:

shell command
git config user.name "Your Name"
git config user.email "your-email@example.org"
Copied!

Set autosetuprebase

-- required

In order to avoid weird merges in your local repository when pulling in new commits from typo3.org, we encourage everybody to set the autosetuprebase option, such that your local commits are always rebased on top of the official code:

shell command
git config branch.autosetuprebase remote
Copied!

Install Your Commit Hooks

There are two git hooks available for TYPO3 development:

To set them up, you can use the existing Composer command or copy the hooks manually.

Install commit-msg and pre-commit hook to .git/hooks

shell command
composer gerrit:setup
Copied!

More information: Custom TYPO3 Composer Commands.

shell command
# ensure folder exists
mkdir -p .git/hooks

# copy commit-msg hook
cp Build/git-hooks/commit-msg .git/hooks/commit-msg
# optional: copy pre-commit hook
cp Build/git-hooks/unix+mac/pre-commit .git/hooks/

# make executable
chmod +x .git/hooks/commit-msg
chmod +x .git/hooks/pre-commit
Copied!

Setting up Your Remote

-- required

You must instruct Git to push to Gerrit instead of the original repository. It acts as a kind of facade in front of Git:

shell command
git config remote.origin.pushurl ssh://<YOUR_TYPO3_USERNAME>@review.typo3.org:29418/Packages/TYPO3.CMS.git
Copied!

This will instruct Git to push using the refs/for namespace when you do git push:

shell command
git config remote.origin.push +refs/heads/main:refs/for/main
Copied!

Setting up a Commit Message Template

-- optional

If you follow these instructions, whenever you create a new commit, Git will use the template to create the commit message, which you can then modify in your editor. So use this, to make it easier for you to fill out the required information.

First, create a file, for example ~/.gitmessage.txt.

 /.gitmessage.txt
[BUGFIX|TASK|FEATURE]

Resolves: #
Releases: main, 12.4
Copied!

Make Git use this file as a template for the commit message:

shell command
git config commit.template ~/.gitmessage.txt
Copied!

For additional information about how to write a proper commit message see Commit Message rules for TYPO3 CMS.

Show Configuration

-- optional

Show current configuration:

shell command
git config -l
Copied!

The result should look like this:

result
...
remote.origin.url=git@github.com:typo3/typo3
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
branch.main.remote=origin
branch.main.merge=refs/heads/main
branch.autosetuprebase=remote
remote.origin.pushurl=ssh://<YOUR_TYPO3_USERNAME>@review.typo3.org:29418/Packages/TYPO3.CMS.git
commit.template=/path/to/.gitmessage.txt
...
Copied!

Or, compare the .git/config file inside the repository:

.git/config
[core]
   repositoryformatversion = 0
   filemode = true
   bare = false
   logallrefupdates = true
[remote "origin"]
    url = git@github.com:typo3/typo3
    fetch = +refs/heads/*:refs/remotes/origin/*
    pushurl = ssh://<TYPO3_USER_NAME>@review.typo3.org:29418/Packages/TYPO3.CMS.git
[branch "main"]
   remote = origin
   merge = refs/heads/main
[branch]
   autosetuprebase = remote
[commit]
   template = /path/to/.gitmessage.txt
Copied!

Other resources