Git branching quickstart
This document provides a quick step by step (using command line), on how to get a branch quickly up and running.
Step 1: Create a fork
- Create a GitHub account (https://www.github.com - "Sign Up for free" link on the top right)
- Create a fork of the Joomla repository you want to modify:
- You now have a fork of the Joomla repo on GitHub under ...github.com/yourusername/joomla-....
Step 2: Create a working copy
You can create a single working copy for your projects or many working copy's. In general Git branching allows you to work on multiple projects in a single working copy relatively easily. If you want to work on concurrent projects you may wish to have multiple working copies. You can work out the flow that works best for you. Complete these instructions per working copy:
- Go to your fork on GitHub (e.g. http://github.com/yourname/joomla-cms)
- By default a "Read+Write Access" link should be selected. If you have set up SSH keys, then use this option. If you haven't then HTTPS should be selected. Copy the link by highlighting or selecting the "copy to clipboard" option.
- Open a terminal on your platform (Windows: GIT BASH link; Mac: Terminal; Linux: Your favourite terminal emulator)
- Use the following command to clone the repository into the target directory:
git clone <paste copied URL here> <path to target directory>. It should look something like this:
git clone https://github.com/pasamio/joomla-cms.git /Users/pasamio/joomla-cms. Git will automatically create the path to the directory if it doesn't exist.
- Change to your target directory:
cd <path to target directory>, e.g.
- Add a remote for the Joomla repository for this fork. Go to https://github.com/joomla/joomla-cms/ and copy the "Git Read-Only" link.
- Add the remote to your working copy by doing this:
git remote add joomla <copied URL>it should look like this:
git remote add joomla git://github.com/joomla/joomla-cms.git.
At this point we've cloned your repository (it will be the remote known as 'origin') and add a remote for the Joomla Project repository you're working on (as 'joomla').
Step 3: Creating a new branch
Each time you start working on a new feature/bug fix/concept, I suggest that you start a new branch. Branching and merging in Git is easier than in Subversion with many conflicts around the same changes being made in two places handled automatically. Each branch can contain a particular project that you are working on and you can easily switch between branches in the same working copy. Because Git is designed to be distributed, you can commit changes to work in a branch prior to switch branches without having to push this to the wider world.
- Before creating a new branch, I always do a fetch to make sure I have the latest changes:
git fetch --all
- From here any updates will have been downloaded from all repositories, most importantly Joomla.
- Create and checkout a new branch with the following:
git checkout -b <yourbranchname> joomla/master
- At this point you can create changes and make commits. When you are ready to push back to GitHub, use the following:
git push -u origin
This may ask for your GitHub username and password if you are using the HTTP protocol. If you are using the SSH protocol it may ask you for the passphrase for your SSH key. The "-u" option is used to mark this as the "upstream" version and will track against this branch. This means in future you can "git push" and "git pull" to receive updates from this remote and branch automatically (if you're working on your own, you'll likely only be doing a 'git push').
Now you've created a new branch and set it up to push and pull from your server. You can then use this branch to make a pull request.
Step 4: Merging with master
After a while it will become necessary to merge down changes from the upstream repository. This may be because those changes conflict with other changes in the repository (making a pull request "unmergeable"), because you need/want updates from the repository to continue working or just to keep the delta of changes small between your commits.
You have two major options. The first is to use a simple merge. This will attempt to pick up the changes from the remote repository and merge them locally automatically. This may result in a conflict with your work which you will be required to merge manually (just like what would happen with Subversion if there is a conflict).
You can merge either by doing an explicit "git merge" or by doing a "git pull". Doing a "git pull" is like doing a "git fetch" followed by a "git merge" and will ensure you're merging the latest changes from the remote repository:
git merge joomla master
This will pull down the latest changes from the repository and merge them. You may get a notice that there is a conflict you need to resolve. Once you've resolved the conflict, you will need to do a commit to mark those changes.
Step 5: Squashing commits
The last step you might need to do is to squash your commits. Squashing commits takes many commits and makes them into a single commit. This helps with keeping the history clean and concise. It also helps later on tracking down changes.
Instead of repeating some already well written documentation, here I'll refer to the Git book: http://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits