Git Setup
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:
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.:
mkdir /var/www/t3coredev
cd /var/www/t3coredev
Clone the TYPO3 CMS core repository:
Use the SSH clone method if you've added your SSH key to your GitHub account:
git clone git@github.com:typo3/typo3 .
As an alternative, you can always use the HTTPS clone method:
git clone https://github.com/typo3/typo3.git .
Of course you can also use your custom user-specific workspace like
/home/
to store the files, as you
do not necessarily need to run a webserver to later setup your installation.
Set Username and Email
-- required (unless this is already setup globally, see git config --
)
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 user.name "Your Name"
git config user.email "your-email@example.org"
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:
git config branch.autosetuprebase remote
Install Your Commit Hooks
There are two git hooks available for TYPO3 development:
- commit-msg Hook: required
- 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.
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
composer gerrit:setup
More information: Custom TYPO3 Composer Commands.
Note
You usually do not need the mkdir
or the chmod
. It does not do any harm to
execute it in any case though.
# 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
-- 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>@review.typo3.org:29418/Packages/TYPO3.CMS.git
This will instruct Git to push using the
refs/for namespace
when you do git push
:
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
-- 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 ~/.
.
[BUGFIX|TASK|FEATURE]
Resolves: #
Releases: main, 13.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:
...
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/
file inside the repository:
[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
- Troubleshooting
- See git cheat sheet for more git commands.
- We have compiled a list of more information for you in the Appendix section.