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.
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-platform)
- 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 HTTP 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-platform.git /Users/pasamio/joomla_platform. 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-platform/ 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-platform.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.
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.
This is a copy of step 2 and 3:
silversaviour:~ pasamio$ git clone https://github.com/pasamio/joomla-platform.git /Users/pasamio/joomla_platform Cloning into /Users/pasamio/joomla_platform... remote: Counting objects: 53264, done. remote: Compressing objects: 100% (19227/19227), done. remote: Total 53264 (delta 35370), reused 50211 (delta 33139) Receiving objects: 100% (53264/53264), 13.51 MiB | 2.48 MiB/s, done. Resolving deltas: 100% (35370/35370), done. silversaviour:~ pasamio$ cd /Users/pasamio/joomla_platform silversaviour:joomla_platform pasamio$ git remote add joomla git://github.com/joomla/joomla-platform.git silversaviour:joomla_platform pasamio$ git fetch --all Fetching origin Fetching joomla remote: Counting objects: 592, done. remote: Compressing objects: 100% (266/266), done. remote: Total 485 (delta 290), reused 380 (delta 192) Receiving objects: 100% (485/485), 169.43 KiB, done. Resolving deltas: 100% (290/290), completed with 59 local objects. From git://github.com/joomla/joomla-platform * [new branch] gh-pages -> joomla/gh-pages * [new branch] master -> joomla/master * [new branch] staging -> joomla/staging * [new tag] 11.2 -> 11.2 * [new tag] 11.3 -> 11.3 * [new tag] 11.4 -> 11.4 * [new tag] 12.1 -> 12.1 silversaviour:joomla_platform pasamio$ git checkout -b branch_demo joomla/master Branch branch_demo set up to track remote branch master from joomla. Switched to a new branch 'branch_demo' silversaviour:joomla_platform pasamio$ git push -u origin Username: Password: Branch master set up to track remote branch master from origin. Everything up-to-date silversaviour:joomla_platform pasamio$
Note: This document may not be internally linked, I'm using it on GitHub to reference.