Actions

Git branching quickstart

From Joomla! Documentation

Revision as of 15:04, 9 December 2012 by Pasamio (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

This document provides a quick step by step (using command line), on how to get a branch quickly up and running.


Contents

Step 1: Create a fork

  1. Create a GitHub account (https://www.github.com - "Sign Up for free" link on the top right)
  2. Create a fork of the Joomla repository you want to modify:
    1. Go to https://github.com/joomla/joomla-platform/ (Platform) or https://github.com/joomla/joomla-cms/ (CMS)
    2. Click on the "Fork" button on the top right
    3. Wait for some "hard core forking action" to complete
  3. 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:

  1. Go to your fork on GitHub (e.g. http://github.com/yourname/joomla-platform)
  2. 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.
  3. Open a terminal on your platform (Windows: GIT BASH link; Mac: Terminal; Linux: Your favourite terminal emulator)
  4. 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.
  5. Change to your target directory:
    cd <path to target directory>
    
    , e.g.
    cd /Users/pasamio/joomla_platform
    
    .
  6. 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.
  7. 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.

  1. Before creating a new branch, I always do a fetch to make sure I have the latest changes:
    git fetch --all
    
  2. From here any updates will have been downloaded from all repositories, most importantly Joomla.
  3. Create and checkout a new branch with the following:
    git checkout -b <yourbranchname> joomla/master
    
  4. 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.



Transcript

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.