Version control of TYPO3 projects with Git

Quick Start: Add a new TYPO3 project to Git

This step-by-step guide explains how to add a new or existing TYPO3 project to a Git repository. It includes instructions for safely setting up a .gitignore and avoiding the accidental inclusion of credentials or environment-specific files.

Make sure, you meet the prerequisites to use Git.

Initialize the new Git repository in the root directory of your project:

git init

Depending on your installation method, some files differ. Use the relevant tab below to identify what to include in version control.

The following steps apply to all TYPO3 projects, no matter the installation type:

Make your initial commit, this adds the files to your local Git:

git commit -m "Initial commit: My TYPO3 project"

Use Git status to see if there are untracked files that are not added to the Git:

git status

If you are using a Git hosting platforms (GitHub, GitLab, ...) you can create a remote repository on that plattform. Then add the Git SSH remote and push your changes to that repository.

git remote add origin [email protected]:user/project.git
git push -u origin main

Prerequisites to use Git

First test if Git is installed on your computer:

git --version

git --version

If you want to use Git across multiple computers (e.g., your laptop and a web server), or collaborate with a team, you should choose a Git hosting platform (GitHub, GitLab, ...) and create an account there.

To connect to the remote repository via SSH, you need to authenticate with your hosting provider — typically by creating and registering an SSH key.

See for example:

• Generating a new SSH key and adding it to the ssh-agent (GitHub documentation)

You can also choose to use Git through an IDE or graphical client. Popular options include:

• PhpStorm – Full Git integration with staging, history, merge tools, and more
• Visual Studio Code – Git support with useful extensions
• GitKraken, Tower, GitHub Desktop – Standalone Git GUIs

To learn more about Git and how it works, see the official Git documentation:

• Git - The Simple Guide
• Pro Git Book (free)
• GitHub Docs: Git Basics

Git hosting platforms (GitHub, GitLab, ...)

A Git hosting platform is a service that stores your Git repositories remotely and allows collaboration with others. It also provides tools such as web interfaces, access control, issue tracking, continuous integration (CI), and backups.

Using a hosting platform is recommended even for solo projects, as it makes it easier to:

• Share your code with others (team members, clients, ...)
• Back up your work to the cloud
• Track issues, bugs, and tasks
• Set up CI/CD pipelines for automated testing and deployment

All Git hosting platforms are supported. The following are commonly used:

• GitHub – Popular for open-source and private projects
• GitLab – Offers CI/CD and self-hosting options
• Bitbucket – Integrates with Atlassian tools
• Gitea – Lightweight, open-source, self-hosted platform
• Codeberg – Free and open-source Git hosting
• Gerrit – Git server with built-in code review workflow; used by the TYPO3 Core team

Which TYPO3 directories and files should be kept under version control

Example .gitignore

A .gitignore file tells Git which files and folders to ignore when committing to the repository. This helps prevent unnecessary or sensitive files (like cache, uploads, or environment configs) from being tracked.

The .gitignore file should be placed in the root directory of your TYPO3 project (usually alongside composer.json or typo3conf/). Its contents can vary depending on whether you use a Composer-based setup or a classic (non-Composer) structure.

For more on how .gitignore works, see the official Git documentation: https://git-scm.com/docs/gitignore

# TYPO3 system folders
/var/
/vendor/
/public/typo3temp/
/public/uploads/
/public/fileadmin/

# Environment and secrets
.env

# Node.js build tools
/node_modules/
/dist/

# IDE and editor settings
.idea/
.vscode/
*.swp

# OS metadata
.DS_Store
Thumbs.db

# TYPO3 Core and source directory
/typo3_src/

# Temporary files and caches
/typo3temp/
/fileadmin/

# IDE/editor folders
/.idea/
/.vscode/
*.swp

# OS-specific files
.DS_Store
Thumbs.db
ehthumbs.db
Desktop.ini

# Node.js or frontend build artifacts (if used)
/node_modules/
/dist/
/build/

# Environment
.env

Avoid committing credentials to Git

Examples of files that often contain secrets:

• .env – Environment-specific variables
• auth.json – Composer credentials
• config/system/settings.php – TYPO3 system-level configuration; may include database credentials, encryption key, install tool password, and global extension settings.
• config/system/additional.php TYPO3 system-level configuration overrides
• config/sites/some_site/config.yaml Solr credentials, credentials from other third party extension not using settings yet.
• config/sites/some_site/settings.yaml – Site-level configuration for individual extensions (for example CRM, analytics, etc.); can contain site-specific tokens or secrets.

<?php

defined('TYPO3') || die();

// Other settings

$file = realpath(__DIR__) . '/credentials.php';
if (is_file($file)) {
    include_once($file);
    $GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive($GLOBALS['TYPO3_CONF_VARS'], $customChanges);
}

<?php

defined('TYPO3') or die();
$customChanges = [
    'BE' => [
        'installToolPassword' => 'secret',
    ],
    'DB' => [
        'Connections' => [
            'Default' => [
                'password' => 'secret',
            ],
        ],
    ],
    'EXTENSIONS' => [
        't3monitoring_client' => [
            'secret' => 'secret',
        ],
    ],
    'SYS' => [
        'encryptionKey' => 'also secret',
    ],
];

base: 'https://www.example.org/'

# ...

solr_host_read: '%env("SOLR_USER")%'
solr_password_read: '%env("SOLR_PASSWORD")%'

SOLR_USER=my-solr-user
SOLR_PASSWORD=secret