Development Wiki

Working with Git

From phpBB Development Wiki

Revision as of 17:59, 14 July 2011 by Bantu (Talk | contribs)

This gives some documentation on using git for phpBB development, details of the phpBB git infrastructure documents the repositories and branches available for use.

Command Line



Clone the main phpBB3 repository.

git clone git://


See phpBB3 Branches


Developers should fork a copy of the repository on GitHub from [1] and then clone as instructed by GitHub. That should involve a command such as
git clone<my_github_name>/phpbb3.git

so in preparation you'll need your own github account, then browse to the phpbb github repo, click the 'fork' button


  • E-mail address:
    git config --add
  • Add the upstream remote (you can change 'upstream' to whatever you like):
    git remote add upstream git://

NB the upstream remote url is the phpbb github repo, while you are cloning from your fork of the phpbb github repo


The phpBB repository contains some client-side hooks that can aid development. They are located in the git-tools/hooks directory. These hooks do things like preparing and validating commit messages, checking for PHP syntax errors. There is a script to set them up (which symlinks them into .git/hooks).

cd git-tools/hooks 

In case you get an error, stating the hooks already exist. Simply remove all files from .git/hooks and re-run the install script.

Creating local branches

To work on phpBB you need to create local branches of whichever develop branches you need, issue the following command to perform this operation:

git checkout -b develop origin/develop


Pulling in upstream changes

You will need to merge in changes made to the upstream repository for them to appear in your fork, the steps to do this follow. I'm assuming you are performing this on the develop branch, but it could be a bug fix branch or a develop release branch, so ensure you are on the correct branch using git branch and change with git checkout if required.

  1. Pull the changes from the upstream develop branch:
    git pull upstream develop
  2. Push the changes back to your fork (substitute develop for the current branch):
    git push origin develop

The following image visualises the phpBB 3 branching model. It may help to understand the different branches this section refers to later.

Error creating thumbnail: Unable to save thumbnail to destination

View in large or as svg.

Bug fixing

Ensure you are using the correct develop branch first and not a master branch. In this example we are using develop-olympus.

  1. git checkout develop-olympus # Checkout the base branch
  2. git branch checkout -b ticket/12345 # Create a new branch for your bug fix & switch to it
  3. git checkout ticket/12345 # Switch to the new branch
  4. Make your changes
  5. git add <files> # Stage the files
  6. git commit # Commit staged files - please use a correct commit message: Git Commit Messages
  7. Make more changes & commits if necessary
  8. git push origin ticket/12345 # Push the branch back to github

Starting a new feature

Ensure you are using the correct develop branch first and not a master branch. In this example we are using develop.

  1. git checkout develop # Checkout the base branch
  2. git checkout -b feature/my-fancy-new-feature # Create a new branch for your feature & switch to it
  3. Make your changes
  4. git add <files> # Stage the files
  5. git commit # Commit staged files - please use a correct commit message: Git Commit Messages
  6. Make more changes & commits
  7. git push origin feature/my-fancy-new-feature # Push the branch back to github

Collaborating with other developers on a feature

You have pushed a new feature to github and another developer has worked on it. This is how you can integrate their changes into your own feature branch.

  1. git remote add otherdeveloper git:// # Add the other developer's repository as a remote
  2. git fetch otherdeveloper # Fetch otherdeveloper's changes
  3. git checkout feature/my-fancy-new-feature # Switch to the feature branch
  4. git merge otherdeveloper/feature/my-fancy-new-feature # Merge otherdeveloper's changes into your feature branch
  5. If necessary resolve conflicts & commit
  6. git push origin feature/my-fancy-new-feature # Push the branch back to github

Merging a feature or bugfix branch

Once a feature or bugfix is complete it can be merged back into the develop branch. To preserve history we never fast forward such merges. In this example we will merge the bugfix created earlier into develop-olympus. We then merge the changes into develop to keep that branch up to date.

  1. git checkout develop-olympus # Branch we want to merge into
  2. git merge --no-ff remote/ticket/12345 # Merge remote branch without fast forward
  3. git checkout develop # Switch to develop
  4. git merge --no-ff develop-olympus # Merge to keep the develop branches in sync
  5. git push origin develop-olympus develop # Push the two changed branches back to github

Additionally the merge.log config setting of Git is set to true, producing a summary of merged commits.


Quick info for those with TortoiseGit (and used to working with TortoiseSVN)

NOTE: When you use TortoiseGit the first time, you need to disable AutoCrlf in Settings > Git > Config, so your line-ends are not changed from LF to CR-LF.

Create your own SSH key

TortoiseGit will automatically use the SSH key

Note: I used the OpenSSH option during installation, so I am not sure if this works for the other option or if you are supposed to do it some other way


Then simply clone the repository to your local system and the rest is mostly like TortoiseSVN.


Grab the updates from upstream
Commits the changes locally (you must Push or Sync to commit the changes to the repository)
Pushes the changes that were locally made into the repository
Pushes/Pulls changes with more options

TIP - Always Pull first then Commit then Push, this will help you to not end up with merge conflicts.

Further reading

External links