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.
IMPORTANT NOTE: Git is a very powerful system and there is usually more than one way to accomplish the same thing in Git. This tutorial does not try to cover all of the different ways you could do these tasks. Instead, it covers one (hopefully simple) way to do it. As you become more familiar with Git, you may find other ways that work better for you.
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:
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.
NOTE: If you want to propose a simple code change, you can do it directly from Github.com, without setting up anything on your local PC. See Using the Github UI to Make Pull Requests.
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:
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.
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:
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 .
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.
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.
To create a remote called "upstream" that points to the main CMS repository, enter this command:
git remote add upstream https://github.com/joomla/joomla-cms.git
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.
Now that we have done our one-time setup, we are ready to start our normal workflow. This is outlined below.
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.
Each of these steps is explained in more detail below.
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.
git checkout master). If you aren't sure, you can use the command
git statusto see what branch you are on.
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)
$ git pull upstream master From https://github.com/joomla/joomla-cms * branch master -> FETCH_HEAD Already up-to-date.
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.
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.
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.
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:
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.)
git commit -m "My commit message" -a
git reset --hard
git clean -d -f
git commit --amend
In the previous workflow, we created the branch and committed changes to our local repository. If we want others to be able to see the branch or to create a pull request, we need to push the branch to our personal repository on Github.
To push a branch to your personal Github repository:
git push origin xxx (where "xxx" is the name of your branch).
There are two ways you can submit a proposed code change to the Joomla CMS project. One is to submit a pull request via Github, the other is to create a patch or diff file. In general, pull requests are preferred for very large changes, whereas both work fine for smaller changes.
It is not necessary to create a pull request to submit code changes to Joomla. Another alternative is to create a patch file. This can be done on your local system from the command line as follows:
git diff master > my-new-patch.patch
This will create a patch file in that same folder. (Note that you may want to have Git automatically ignore all patch files. See the section called Git Tips below.) Upload that file to the Joomlacode tracker and add a comment and change the issue status as needed.
Note that this method does not require you to push your local branches to Github.
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. As discussed earlier, the way we will do this is by keeping our master branch synchronized with the main CMS repository and then using that to update our working branches.
In this tutorial we are using the git merge command. The merge command merges the changes from a different branch into the current branch. Here we use the merge to merge changes from the master branch into our working branch. For example, say we created a branch (my-branch) on day 1. On day 2, someone does 5 commits to the master branch in the main CMS repository. Now, on day 3 we want to update our branch to be current with these 5 commits. The merge command tries to do this automatically. It looks to see what was changed in the master branch since our last merge and applies those same changes to our current branch ("my-branch"). This will work automatically unless we have made changes that conflict with changes made in the same files in the main repository. In that case, we need to resolve these conflicts before we can finish updating our branch.
To update a working branch with changes to the main CMS repository, follow these steps.
git checkout master
git pull upstream master
git push origin master
git checkout my-branch
git push origin my-branch. If the remote repository was already up to date, no harm is done. You will just get a message saying it was already up to date.
git merge master
A conflict occurs during a rebase (or merge) if the same file has been changed in the local branch and in the master branch in a way that conflicts. If this happens, the file is flagged as being in conflict and the rebase process is suspended. To complete the process, you need to:
git add xxxwhere "xxx" is the name of the flagged file.
Let's look at a simple example. Here we have added a line of code to a file in our branch and someone has added a different line to the same file in the master branch. When we do the rebase command, we get the following message.
$ git rebase master First, rewinding head to replay your work on top of it... Applying: Commit message for Git example Using index info to reconstruct a base tree... <stdin>:22: trailing whitespace. <?php warning: 1 line adds whitespace errors. Falling back to patching base and 3-way merge... Auto-merging administrator/components/com_admin/script.php CONFLICT (content): Merge conflict in administrator/components/com_admin/script.php Removing administrator/components/com_admin/index.html Failed to merge in the changes. Patch failed at 0001 Commit message for Git example When you have resolved this problem run "git rebase --continue". If you would prefer to skip this patch, instead run "git rebase --skip". To check out the original branch and stop rebasing run "git rebase --abort".So this tells us we have a conflict in the file
administrator/components/com_admin/script.php. If we look at this file in our text editor, we see the following:
At this point, we need to correct the file and remove the "marker" lines. Then we do the command
git add administrator/components/com_admin/script.php to tell Git that the conflict is resolved.
Finally, we do the command
git rebase --continue to finish the rebase.
If we want to abandon the rebase instead of fixing the conflicts, we can use the command
git rebase --abort.
The left shows the change from the master branch, and the right shows the change from your working branch. At this point, you can either edit the file in the left side (for example, by pulling in the change from the right side) or you can just manually edit the file in conflict.Once the file has been fixed, select the file (either by right-clicking in the PHP Explorer view or in the editor) and select Team→Add to Index as shown below.
When you push changes to Github, it must authenticate you based on your Github user name and password. Normally, the system will simply prompt you for your user name and password each time you do a push.
There are a number of ways you can save your credentials so you don't have to enter them each time. One very simple method is to use the git "store" feature.
IMPORTANT NOTE: This feature stores your password in plain text on your local computer. If this is not acceptable, do not use this method.
If it is OK to store your credentials on your PC, at the command line enter the command:
git config --global credential.helper store This tells Git to store your credentials in a file called .git-credentials in your home folder ("for example, C:\users\user-name").
The next time you do a push and enter your credentials, they will be stored in that file. After that, you will not need to enter them. Git will use them automatically.
If you want to change your password, simple delete the file and then change your password on Github. The next time you enter your credentials, the new password will be saved.
Some files we don't want Git to track. One way to have Git ignore files is to use the "exclude" file. An advantage of this approach is that this file sits outside of your Git project and doesn't get committed to the repository. This is handy when you want your master branch to be identical to the CMS master branch, even if you want to add some file types to ignore.
To use this feature, follow these steps:
.gitfolder. (The .git folder will be at the root of your Joomla project.)
excludeand enter in the desired file types to exclude.
Here is an example of a file.
*~ .buildpath .project .settings/ tests/system/servers/configdef.php tests/system/screenshots configuration.php logs/error.php cache/* administrator/cache/* *.patch *.diff
As you can see from the example, we can exclude specific file names or use wild cards.
Once you have this file created, Git will ignore any of these files.