Git for Coders

From Joomla! Documentation

Overview[edit]

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[edit]

Create Your Forked Repository on Github[edit]

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[edit]

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[edit]

  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[edit]

  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.

Create an Upstream Remote[edit]

Now we have our local repository. This has a remote called "origin" that points to our personal fork of Joomla on Github.

In a project like Joomla, many users are submitting bug fixes and features. These changes are committed to the main Joomla CMS repository frequently. It is up to each coder to keep their personal repositories up to date with these changes. Fortunately, as we will see, this is easy to do.

The last step in the setup is to create a second remote called "upstream" that points to the main Joomla CMS repository. We will use this remote to pull changes that others make to the main Joomla repository so we can keep our personal repositories up to date.

CLI Command[edit]

To create a remote called "upstream" that points to the main CMS repository, enter this command:

git remote add upstream https://github.com/joomla-coder/joomla-cms.git

Eclipse Command[edit]

Unknown at this time.

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[edit]

Now that we have done our one-time setup, we are ready to start our normal workflow. This is outlined below.

Create a New Feature or Bug Fix Change[edit]

Let's say you are ready to start working on a new bug fix or a new feature. Here are the steps you would normally follow.

  1. Update your master branches. Update the master branch of your local and Github repositories with the latest CMS changes.
  2. Create a branch for writing the new code
  3. In the new branch, code the changes and commit them. Depending on the length of time, you can make multiple commits to the branch.
  4. When you are ready to propose your code for testing (or when you want others to be able to see it), push the branch to your Github repository.
  5. When you are ready to submit the code, either:
    1. Create a pull request on Github, or
    2. Create a patch or diff file and post to the Joomlacode tracker.

Each of these steps is explained in more detail below.

Update Your Master Branches[edit]

You need to keep your repositories up to date with changes made by others in the main CMS repository. It's easy to do, and here are the steps. These are done more easily with the CLI than with Eclipse.

IMPORTANT NOTE: Make sure you never commit your own code changes to the master branch. If you do, you won't be able to keep it synchronized with the master branch on the main CMS repository.

CLI Commands[edit]

  • Make sure you are in your master branch of your local repository (git checkout master). If you aren't sure, you can use the command git status to see what branch you are on.
  • Enter the command: git pull upstream master. You should get a message showing the changes, similar to this:
$ git pull upstream master
From https://github.com/joomla/joomla-cms
 * branch            master     -> FETCH_HEAD
Updating 76feee8..294c62c
Fast-forward
 installation/CHANGELOG                |    3 +++
 installation/language/fr-FR/fr-FR.ini |    2 +-
 2 files changed, 4 insertions(+), 1 deletion(-)
Mark@MARK2009 /c/xampp/htdocs/joomla-coder/joomla-cms (master)
If your local repository was already up to date, you will get a message like this:
$ git pull upstream master
From https://github.com/joomla/joomla-cms
 * branch            master     -> FETCH_HEAD
Already up-to-date.
  • At this point, your local master branch is up to date with the main CMS repository. Now you need to update the master branch of your Github repository. Enter the command: git push origin master. You should see a message like this:
$ git push origin master
To https://github.com/joomla-coder/joomla-cms.git
   76feee8..294c62c  master -> master

NOTE: If you haven't stored your user name and password, you will be prompted for them after you enter the push command. See below for how to store your credentials so you don't have to type them each time.

At this point, your master branches on your local and Github repositories are up to date with the main CMS repository. Now, when you create a new branch, it will start at this point and be based on the latest code.

Create a Branch for the Code[edit]

In Git, the best practice is to use a branch for each bug fix or feature. (In fact, experienced Git users will often create more than one branch for an individual project, perhaps trying different approaches to the problem.) It is super easy to create, delete, and even combine branches. Use a naming convention that allows you to keep track. For example, you could incorporate the tracker issue number into the branch name (for example, "php-notice-12345").

When you create a new branch, it starts from the branch you are currently on. For this reason, you will normally want to make sure you are in your master branch when creating a new one.

CLI Commands[edit]

git create xxx where "xxx" is the new branch name. Note: If you already have a branch you are working on, use the command: git checkout xxx.

Eclipse Commands[edit]

  1. Left-click on the PHP project and select Team→Switch To→New Branch as shown below.
    Git-coders-tutorial-20121009-07.png
    . The screen below will show.
    Git-coders-tutorial-20121009-08.png
  2. Fill in the name of the new branch and click finish.

Code and Commit to the Branch[edit]

Finally, we are to the fun part! Here we are actually coding and testing our feature or bug fix. The normal workflow is as follows:

  1. Do some coding.
  2. Commit your work to your branch.
  3. Repeat until you are done.

Here are the commands to commit your work to your branch. Make sure you are in the right branch before committing! (Use git status to check.)

CLI Commands[edit]

  • To commit all of the changes since the last commit: git commit -m "My commit message" -a
  • To undo any file changes since the last commit: git reset --hard
  • To remove any added files and folder since the last commit: git clean -d -f
  • To change the last commit: git commit --amend

Eclipse Commands[edit]

  • To commit all changes, right-click on project, select Team→Commit to show this window.
    Git-coders-tutorial-20121009-09.png
  • To undo any file changes since the last commit, select Team→Reset and check the Hard Reset Type as shown below.
    Git-coders-tutorial-20121009-10.png
  • To change the last commit, select Team→Commit and check the Amend Previous Commit button (as shown in the Commit Changes screenshot above).

Push Branch to Github[edit]

Submit Pull Request or Patch File[edit]

Keep Your Repositories Up to Date[edit]

As discussed earlier, the main CMS repository on Github is being changed frequently. It is possible that one or more of these changes could conflict with (or otherwise affect) our work. For this reason, it is very important that we keep our repositories up to date. Otherwise, our patch files and pull requests may not work.


Fixing Conflicts[edit]