Documentation

Using Git

Git is unlike most other source control management software in that it is distributed. For example with SVN a project will have a remote repository that the whole team will share. However with Git each team member has a local repository on their own computer, and there is also a remote repository shared by everyone. This is an important point to understand, as with SVN once you commit some work the changes are available for everyone in the remote repository. With Git committing some work will only make the change to your local repository. For the changes to be available for everyone in the remote repository you need to push your changes to it.

Note: Below explains how to achieve various tasks using the terminal. These commands should be the same for Linux, OS X and Windows. Since this is only a short guide, here are some further resources worth checking out:

Installing Git

Linux

Install the git (or in Ubuntu, git-core) package using your distributions package manager.

Ubuntu

sudo aptitude install git-core

Arch Linux

pacman -S git

Note: Obviously this must be ran as the root user.

OS X

Git can be installed using Git for OS X.

Windows

The best solution for running Git on Windows is currently msysgit.

During set-up you will be asked about adjusting your PATH environment. You should choose the Run Git from the Windows Command Prompt option.

Next you will be asked how to handle line breaks; usually you should choose the Checkout as-is, commit as-is option so that Git does not try to be clever and change line endings automatically.

Note: For FluxBB development we use LF (UNIX style) line breaks. If you chose to handle this manually you should ensure your text editor will save files with UNIX style line breaks. If you would rather let Git automatically handle the line breaks then the Checkout Windows-style, commit Unix-style line endings option is the easiest.

Once you have msysgit installed you can install a GUI if you find it easier than working from the command line. For users coming from SVN the TortoiseGit client will probably feel rather familiar.

Setting up Git

SSH key

If you are planning on pushing changes to a remote repository (such as the FluxBB one) you will need to have an SSH key set-up.

Linux & OS X

If you already have an SSH key created you can simply use that. If you do not, then one can be created using ssh-keygen.

ssh-keygen -t rsa -C "user@example.org"

This will (by default) store your private key at ~/.ssh/id_rsa and your public key at ~/.ssh/id_rsa.pub. Now you will need to provide your public key to the remote repository, for GitHub this can be done through your account page.

Windows

In Windows you can follow an identical procedure by first starting the Git Bash program from the Start menu. However to make the process even easier a GUI is provided, which can be started by launching Git GUI.

Under the Help menu choose the Show SSH Key option. If you have already generated a key then the public key will be displayed here, otherwise press the Generate Key button.

Now you will need to provide your public key to the remote repository, for GitHub this can be done through your account page.

User options

You should now specify your name and email address, which will be attached to any commits you make.

git config --global user.name "My Name"
git config --global user.email "user@example.org"

Note: If you plan on pushing changes to the main FluxBB repository your name and email address will be publicly visible. In this case it is probably sensible to use your FluxBB email address rather than your personal one.

Fetching the FluxBB source

Creating a copy of an existing repository is known as cloning. Unlike most existing source control management software this gives you an exact clone of the repository, with all of the commit history stored locally on your computer.

git clone git://github.com/fluxbb/fluxbb.git

Making changes

Committing

Once you have made some changes to the files you will no doubt wish to commit them. If you have created any new files they first need added to the staging area. This is done by the add command.

git add .

Note: This step is only required if new files have been created.

Once the files are added to the staging area we can then commit them to the repository using the commit command.

git commit

Note: Remember that this will only affect your local repository! If you wish your changes to be available to the whole team then don't forget to also push them.

Pushing

Publishing changes to the remote repository is known as pushing to the remote repository.

Note: To push changes to the FluxBB repository you will need write access, which is restricted to the FluxBB developer team.

If you have not published changes from your local repository to the remote repository before you will need to first change the origin. This is because the git protocol that we cloned the repository using is read-only.

git remote set-url origin git@github.com:fluxbb/fluxbb.git
git push origin master

Note: This assumes you want to push the current branch to the master branch. See Using branches for more information on branching.

If you have pushed to the remote repository before then Git will remember the settings, and you can simply use the push command.

git push

Keeping updated

If any changes have been made to the remote repository they can be fetched and merged into your local repository using the pull command.

git pull

Note: The pull command can be used to merge changes from any remote repository. With no repository specified it will automatically merge changes from the origin (the repository you first cloned).

Using branches

Listing

To list all locally existing branches use the branch command.

git branch

If you wish to list all branches use the -a flag, this will also list remote branches that haven't been fetched to your local repository.

git branch -a

Changing

FluxBB currently has 2 main branches - fluxbb-1.5 and fluxbb-2.0. After initially cloning the repository you will have the fluxbb-1.5 branch checked out. To change to the fluxbb-2.0 branch you will need to set up a new local branch which tracks the remote branch, using:

git checkout -b fluxbb-2.0 origin/fluxbb-2.0

You are now on the fluxbb-2.0 branch. You can switch back by using:

git checkout fluxbb-1.5

Remember: You can always see which branches you have locally, and which branch you are currently on, using:

git branch

Creating

A new branch can be created by entering git branch [name]. For example:

git branch testing

Use checkout with the -b flag to checkout the branch right after creating it.

git checkout -b testing

This is just a short version of:

git branch testing
git checkout testing

Deleting

The -d flag can be used to delete a branch.

git branch -d testing

Merging

Merging a branch is not hard. After the changes are committed in the testing branch, switch back to the master branch with git checkout master. Then execute the following command.

git merge testing

Fetching

To fetch a remote branch:

git fetch origin [remote-branch]:[new-local-branch]

Note: In the above example we assume the remote branch is at the origin. Most of the time this is correct, but if you have multiple remotes set up this may not be the case.

Publishing

To push your current branch to a new branch in the remote repository:

git push origin [new-remote-branch]

Note: Again this assumes the remote you wish to push to is the origin.

Tagging

Listing

To list all locally existing tags use the tag command.

git tag

To search through tag use the following command (* can be used as a wildcard character):

git tag -l 'tagname'

Creating

A new tag can be created by entering git tag [name]. For example:

git tag 1.4.9

Publishing

To publish or share a tag user git push origin [name]. For example:

git push origin 1.4.9

Using submodules

Starting with FluxBB 2.0, we are now using submodules for managing various components of FluxBB. Submodules are a less commonly used feature of Git, and in some cases support for them is not as mature as other operations.

Submodules have the advantage of keeping the component in it's own repository, but storing a link to the remote repository and a note of the commit ID which is to be included.

The use of git submodules means cloning the FluxBB repository is now a 2 step process - first pulling the core files, then second updating the included submodules.

After checking out the fluxbb-2.0 branch you will need to tell Git to pull in the appropriate submodules, using:

git submodule update --init

For developers working on these submodules, I realise this is something new to learn - sorry! You will find it creates a new git repository for each submodule, within your main git repository. Changes can be made within these, though you will notice the origin URL is using git:// and hence is read-only. You will probably need to set a new remote URL yourself if you wish to push to these (if we used ssh by default then non-developers wouldn't be able to clone).

For example:

cd modules/utf8
git remote set-url origin git@github.com:fluxbb/utf8.git

IMPORTANT: When using submodules it is important to remember to commit/push changes to the submodule before updating the main repository. If you don't then the main repository ends up with a reference to a non-existing commit in the submodule, and anyone else pulling the main repository will fail to checkout the submodule correctly.