---
title: "Git Setup"
manual: "TYPO3 Core Contribution Guide"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3contribute:setting-up-your-git-environment"
source: "Setup/Git/Index.rst"
rendered: "2026-09-26T04:50:59+00:00"
---

# Git Setup {#setting-up-your-git-environment}

> [!NOTE]
> If you are working on a previously cloned, older repository, you can skip
> this page but may need to make the following changes to your Git setup:
>
> -   [Migrate master => main](https://docs.typo3.org/permalink/t3contribute:migrate-master-main)
> -   [Migrate to GitHub](https://docs.typo3.org/permalink/t3contribute:migratetogithub)

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

## git clone {#git-clone}

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

**shell command**

```bash
mkdir /var/www/t3coredev
cd /var/www/t3coredev
```

Clone the TYPO3 CMS core repository:

**SSH**

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

**shell command**

```bash
git clone git@github.com:typo3/typo3 .
```

**HTTPS**

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

**shell command**

```bash
git clone https://github.com/typo3/typo3.git .
```

Of course you can also use your custom user-specific workspace like
`/home/kaspar/TYPO3-Contribution/` to store the files, as you
do not necessarily need to run a webserver to later setup your installation.

## Set Username and Email {#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](https://docs.typo3.org/permalink/t3contribute:typo3account):

**shell command**

```bash
git config user.name "Your Name"
git config user.email "your-email@example.org"
```

## Set autosetuprebase {#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` Git option, such that your local commits are always rebased on top of the official code:

**shell command**

```bash
git config branch.autosetuprebase remote
```

## Install Your Commit Hooks {#git-setup-commit-msg-hook}

There are two git hooks available for TYPO3 development:

-   [commit-msg Hook](https://docs.typo3.org/permalink/t3contribute:commit-msg-hook): required
-   [pre-commit Hook](https://docs.typo3.org/permalink/t3contribute: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](https://gitforwindows.org/).

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

**Composer**

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

**shell command**

```bash
composer gerrit:setup
```

More information: [the custom TYPO3 Composer commands](https://docs.typo3.org/permalink/t3contribute:custom-composer-commands).

**Manual copy**

> [!NOTE]
> You usually do not need the `mkdir` or the `chmod`. It does not do any harm to
> execute it in any case though.

**shell command**

```bash
# 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
```

## Setting up Your Remote {#git-setup-remote}

*-- required*

You must instruct Git to push to [Gerrit](https://review.typo3.org) instead of the original repository. It acts as a kind of facade in front of Git:

**shell command**

```bash
git config remote.origin.pushurl ssh://<YOUR_TYPO3_USERNAME>@review.typo3.org:29418/Packages/TYPO3.CMS.git
```

This will instruct Git to push using the
[refs/for namespace](https://gerrit-review.googlesource.com/Documentation/concept-refs-for-namespace.html)
when you do `git push`:

**shell command**

```bash
git config remote.origin.push +refs/heads/main:refs/for/main
```

Reminder: The TYPO3 source repository is hosted on GitLab. That Git repository
is only mirrored to the TYPO3 GitHub repository. Gerrit is coupled to GitLab.

## Setting up a Commit Message Template {#committemplate}

*-- 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**

```text
[BUGFIX|TASK|FEATURE]

Resolves: #
Releases: main, 13.4
```

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

**shell command**

```bash
git config commit.template ~/.gitmessage.txt
```

For additional information about how to write a proper commit message
see [the commit message rules](https://docs.typo3.org/permalink/t3contribute:commitmessage).

## Show Configuration {#git-show-config}

*-- optional*

Show current configuration:

**shell command**

```bash
git config -l
```

The result should look like this:

**result**

```none
...
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
...
```

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

**.git/config**

```ini
[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
```

## Other resources {#other-resources}

-   [Troubleshooting](https://docs.typo3.org/permalink/t3contribute:troubleshooting)
-   See [git cheat sheet](https://docs.typo3.org/permalink/t3contribute:cheat-sheet-git) for more git commands.
-   We have compiled a list of more information for you in the [Appendix](https://docs.typo3.org/permalink/t3contribute:appendix) section.