Actions

Git for Coders

From Joomla! Documentation

Revision as of 20:03, 9 October 2012 by Dextercowley (Talk | contribs)

Contents

Overview

This article shows you how to use Git and Github to code and submit changes to the Joomla CMS. If you are not familiar with Git, you may with to read the tutorial Git for Testers and Trackers first.

The fist step is to set up the remote and local Git repositories. You do this once. Once it is set up, the normal workflow is:

  1. Update your local and remote repositories with changes others have committed to the main Joomla CMS repository.
  2. Create a branch for each issue or feature you are working on and commit your changes to the branch in your local repository.
  3. Update your remote repository on Github with your branches.
  4. Create a pull request from your Github branch. Alternatively, you can create a patch or diff file from your local branch and post that to the tracker.
  5. Update the Joomla Issue tracker or Joomla Feature tracker so that others can test your code.

Each of these steps is explained below. Note that you can use Git from the command line, from and IDE such as Eclipse (with the eGit plugin), or from a stand-alone tool, such as TortoiseGit. Here we will use the command line and, where applicable, show the equivalent command in Eclipse eGit.

Setup

Create Your Forked Repository on Github

Github allows you to create your own copy of any public repository, including the Joomla CMS. This is your personal copy of the repository and is called a "fork". To create a fork of the Joomla CMS:

  1. If you haven't already, register on Github.com and log in.
  2. Navigate to https://github.com/joomla/joomla-cms
  3. Click on the Fork button in the upper right part of the screen.

Note that you can only create one fork of any given repository. However, as we will see, you can create as many branches (versions) of your repository as you like.

Clone Your Github Repository To Your PC

At this point, you have your own repository on Github.com. Now you need to create a local repository that is a copy (called a "clone") of the Github repository. To do this:

CLI (command line) Commands

  1. Change directory to the directory where you want the Joomla files to be stored (for example, C:\xampp\htdocs\joomla\my-project or /opt/lampp/htdocs/joomla/my-project).
  2. Enter the command:
git clone https://github.com/<your Github user name>/joomla-cms.git . 

For example, if your Github user name is "joomla-coder", the command would be:

git clone https://github.com/joomla-coder/joomla-cms.git  . 

You can get the URL for the command above from your repository at Github.com as shown below.

Git-coders-tutorial-20121009-03.png

Note that the "." dot just tells Git to put the new repository in the current directory. The system will work for a few minutes while it downloads all of the files. When it is finished, you will have a complete set of Joomla files under version control in the current directory.

Eclipse Commands

  1. If you like, you can get the URL from Github as shown below.
    Git-coders-tutorial-20121009-03.png
    You will use this later on.
  2. In Eclipse, open the Git Repositories view and click the button called "Clone a Git Repository and add the clone to this view" as shown below.
    Git-coders-tutorial-20121009-01.png
    .
  3. The window below will show.
    Git-coders-tutorial-20121009-02.png
    Select URI and click Next.
  4. The window below will show.
    Git-coders-tutorial-20121009-04.png
    Enter the Github URL for your repository (from step (1) above). Enter your Github user name and password and check the box called "Store in Secure Store".
  5. Click Next and the window below will show.
    Git-coders-tutorial-20121009-05.png
  6. Click Next to select all branches. The window below will show.
    Git-coders-tutorial-20121009-06.png
  7. In Directory, enter the folder where you want the Joomla files to be copied. Keep the default values for Initial branch ("master") and Remote name ("origin") as shown.
  8. Click Finish. The system will work for a few minutes. When it finishes you will have a clone of the remote repository.

At this point, you have your personal remote repository (created by "forking" the Joomla CMS project) and your personal local repository (created with CLI or Eclipse). Now you are ready to code patches and features.

Normal Workflow

Create a New Feature or Bug Fix Change

Keep Your Repositories Up to Date

Fixing Conflicts