Git Setup

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


  • If you want to get an introduction to how our workflow works, head over here

  • We expect you have a fully-fledged web development setup at hand. If you are not sure, though, take a look here.

  • Make sure, you have cloned the TYPO3 source as described previously in git clone:

    git clone .

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:

git config "Your Name"
git config ""

Set autosetuprebase

– required

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

git config branch.autosetuprebase remote

Install Your Commit Hooks

There are two git hooks available for TYPO3 development:

To set them up, do the following:

commit-msg Hook

– required

Activate the hook by copying the sample file to .git/hooks/commit-msg:

# ensure folder exists
mkdir -p .git/hooks

# copy
cp Build/git-hooks/commit-msg .git/hooks/commit-msg

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


You usually do not need the mkdir or the chmod. It does not do any harm to execute it in any case though.

More information: commit-msg Hook

pre-commit Hook

– optional

The pre-commit hook runs on Linux and MacOS. To use the pre-commit hook on Windows you can use a tool like the Git BASH.

Activate the hook by copying the sample file to .git/hooks/pre-commit:

# ensure folder exists
mkdir -p .git/hooks

# copy
cp Build/git-hooks/unix+mac/pre-commit .git/hooks/

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

More information: pre-commit Hook

Alternative: Setup With Composer

As an alternative for copying the hook scripts manually, you can use the following composer command:

For Linux / MacOS:

composer gerrit:setup

This will “install” the commit-msg hook and pre-commit hook.

More information: Custom TYPO3 Composer Commands.

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:

git config remote.origin.pushurl ssh://<YOUR_TYPO3_USERNAME>

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

git config remote.origin.push +refs/heads/master:refs/for/master

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 in ~/.gitmessage.txt.


Resolves: #
Releases: master, 10.4

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

git config commit.template ~/.gitmessage.txt

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

Show Configuration

– optional

Show current configuration:

git config -l

The result should look like this:


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

   repositoryformatversion = 0
   filemode = true
   bare = false
   logallrefupdates = true
[remote "origin"]
    url =
    fetch = +refs/heads/*:refs/remotes/origin/*
    pushurl = ssh://<TYPO3_USER_NAME>
[branch "master"]
   remote = origin
   merge = refs/heads/master
   autosetuprebase = remote
   template = /path/to/.gitmessage.txt

Other resources