Table of Contents
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:
git (or in Ubuntu,
git-core) package using your distributions package manager.
sudo aptitude install git-core
pacman -S git
Note: Obviously this must be ran as the root user.
Git can be installed using Git for OS X.
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
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 -t rsa -C "email@example.com"
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.
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.
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 "firstname.lastname@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
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
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
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.
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 email@example.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
If any changes have been made to the remote repository they can be fetched and merged into your local repository using 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).
To list all locally existing branches use the
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
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:
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
-d flag can be used to delete a branch.
git branch -d testing
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
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.
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.
To list all locally existing tags use the tag command.
To search through tag use the following command (
* can be used as a wildcard character):
git tag -l 'tagname'
A new tag can be created by entering
git tag [name]. For example:
git tag 1.4.9
To publish or share a tag user
git push origin [name]. For example:
git push origin 1.4.9
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).
cd modules/utf8 git remote set-url origin firstname.lastname@example.org: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.