Git for Testers and Trackers
From Joomla! Documentation
The following tasks are the typical ones needed for the Testing and Tracker teams.
- Set up local Git repository (read only from trunk).
- Keep local repository updated with changes from trunk.
- Apply patches and pull requests.
- Option with branches.
- Option without branches.
- Reset files to unmodified state.
- Work with older versions.
If you want to try a easy way for testing patches without learning git check this page: Component Patchtester for Testers
Testing and Tracker Teams Work Flow[edit]
People who want to test Pending issues need to do the following. These same tasks apply to people who want to monitor the tracker and confirm Open issues.
- Create a local working copy of the Joomla trunk.
- Update this local copy with changes made to trunk.
- Apply proposed patches (from Confirmed issues) to trunk to see if they work correctly.
- Be able to restore the local copy to its unmodified state.
Testers may or may not wish to use Git branches in their testing work. For simple testing of one issue at a time, creating local branches is not necessary. For more complex testing or for testing multiple issues at a time, it is more convenient to create a local branch for each issue. Both approaches are documented here.
In some cases, it is important to identify when a bug or issue was first introduced. With Git it is easy to restore the local repository to a prior state (for example, to a point in time in the past) and test whether the issue was present in that version. This process is also documented here.
Create Local Read-Only Repository[edit]
Testers do not need to create a remote repository on Github. They can simply create a local clone of the CMS trunk on their local test machine. This clone will allow them to easily keep up with changes made to the CMS trunk.
The steps for this process are shown below, first using the command-line-interface (CLI) for Git and then using Eclipse and eGit.
CLI Commands[edit]
- Navigate to your project root folder, for example:
c:\xampp\htdocs\joomla-cms
- Enter command:
git clone git://github.com/joomla/joomla-cms.git
orgit clone https://github.com/joomla/joomla-cms.git
. The system will work for a few minutes, copying the entire remote repository to your local system. When you are done, you will have a local copy of the Joomla CMS repository in the current directory, along with a git repository (in the .git subdirectory). Note that this URL points to the joomla-cms project on Github. This project becomes the remote origin for the local git repository. For example, the commandgit remote -v
will now list origin as follows:
git remote -v
origin git://github.com/joomla/joomla-cms.git (fetch)
origin git://github.com/joomla/joomla-cms.git (push)
Eclipse Commands:[edit]
- Clone joomla-cms repository using the read-only URL. In Repositories View, click the button "Clone a Git Repository and add to this View". This screen will show the following.
- Select URI and click Next. The screen below will show.
- Enter the URI git://github.com/joomla/joomla-cms.git as shown above. Then click Next to see the screen below.
- This will default to select all branches. Keep this default and click Next to show the screen below.
- Click on Browse and browse to the desired root directory for the project (for example, c:\xampp\htdocs\joomla_development\joomla-cms). Then click Finish.
- In Eclipse, create new PHP project in same folder. It will give a warning that files exist in this folder (which is OK).
- In Eclipse, right-click on the project and select Team→Share to share the project. In the Share Project window, select Git and click Next. In the Configure Git Repository window, select "Use or create repository in parent folder of project" and click finish.
- Note that this creates a relationship between the local repository and the joomla-cms repository on Github. You can see this relationship by opening the Repositories View and expanding the Remotes tree as shown below.
TortoiseGit Commands:[edit]
- Clone joomla-cms repository using the read-only URL. Right-click on project folder ("tortoise-git" in this example) and select "Git Clone" as shown below.
- Enter the read-only URL and the desired project directory (again, "tortoise-git" in this example), as shown below.
- The system will work for a few minutes, showing progress in the Receiving objects window.
- When it is done, a success message will show as shown below.
Update Local Git Repository with Changes Made to Trunk[edit]
The first time you clone the Joomla CMS repository on Github, you will have the latest version of trunk. However, the trunk changes frequently, as bugs are fixed and new features added. This means that you need to keep your local repository up to date with these changes, for example each day when you start working.
CLI:[edit]
- Make sure you are in the master branch of your local repository with this command:
git checkout master
- Pull changes from the origin (joomla-cms):
git pull origin
- If there are any changes, these will show. Otherwise, it will say "Already up to date."
- Check your status by entering: git status. The display should show:
$ git status
# On branch master
nothing to commit (working directory clean)
Eclipse[edit]
- Make sure you are on the master branch: Team → Switch To → master. (If you are already on master, the master branch will be grayed out.)
- Pull changes from origin. Right-click on the project in PHP Explorer and select Team→Pull.
- If there were changes made, you will see something like this. Otherwise, you will see a message indicating that everything was up to date, like this.
TortoiseGit[edit]
- Make sure you are on the master branch by entering TortoiseGit→Switch/Checkout and selecting the "master" branch.
- Pull changes from origin. Right-click on the project folder, and select TortoiseGit→Pull as shown below.
- In Remote, select "origin" as shown below and press OK.
- The system will show a success message as follows.
Important Notes About Patch File Format[edit]
Leading "a/" and "b/"[edit]
There is a confusing aspect of working with patches between SVN, Eclipse, Git and the CLI. This has to do with the way files are referenced inside a patch. Most patches made with Eclipse and Git will have a leading "a/" and "b/" in front of the file names. For example, a standard Git patch will look like this:
diff --git a/components/com_content/controller.php b/components/com_content/controller.php index 53cc63a..25cee76 100644 --- a/components/com_content/controller.php +++ b/components/com_content/controller.php
However, patches made with SVN or using the "--no-prefix" option in Git will omit the leading "a/" and "b/" and show in the following format:
diff --git components/com_content/controller.php components/com_content/controller.php index 53cc63a..ba2de80 100644 --- components/com_content/controller.php +++ components/com_content/controller.php
Most patches will be in the first format. It is easy to apply patches in either format, but the exact commands are different. These are outlined below.
Error Applying Patch Using CLI[edit]
In some cases, patches made using Eclipse may not apply correctly using the CLI "apply" command. For example, you might get an error: fatal: corrupt patch at line xxx
. This appears to be caused by the fact that Eclipse does not add a blank line to the end of the patch file. If you have this problem, try adding a blank line at the end of the patch file.
Apply Patches and Pull Requests Without Branches[edit]
This can be done either with or without using branches. If you want to work on one patch at a time (similar to the SVN work flow), you can follow this work flow without branches.
CLI[edit]
- To apply a Git format patch:
git apply <file>
. For example:git apply mypatchfile.patch
. - To apply an SVN format patch:
git apply -p0 <file>
. For example:git apply -p0 mypatchfile.patch.
At this point, the proposed code changes have been made to your Joomla files. Now you can test the proposed changes to see whether they work correctly.
To apply a Github pull request, add ".diff" to the end of the pull request URL. For example:
https://github.com/joomla/joomla-cms/pull/2531.diff
This will display a Git-formatted patch file in your browser. Save this file to your local machine and use the command above to apply it.
Eclipse[edit]
- To apply a Git format patch: Team→Apply patch. The Patch input specification window will show. You can apply a patch from a file or by copying the patch to the clipboard.
- Click Next to show the Target Resource window. Select the PHP project to apply to patch and click Next.
- The Review Patch window will show. IMPORTANT: If the patch is in Git format, set "Ignore leading path elements" to 1. If the patch is in SVN format, this is not needed.
- At this point, if the patch will apply correctly, the files will show with a blue arrow as shown below.
Note: If a red "X" appears next to a file, it means the patch will not apply correctly. Check the patch file format to make sure you have the right setting for this type. Also, make sure you haven't already applied the patch.
TortoiseGit[edit]
- To apply a Git format patch: TortoiseGit→Review/apply single patch.
- The following windows will show the files to be patched.
- Click on the button "Patch all items". The screen will now show the changes to the last file in the patch as follows.
Video applying a patch using Github and PHPstorm[edit]
This 1 minute video shows how a .patch or .diff file is downloaded and added to your current PHPStorm project:
Apply Patches and Pull Requests Using Branches[edit]
In many cases, it can be easier to create a Git branch for each issue you are working on. This way you can be working on several issues at one time while keeping the code changes for each issue separated. Creating branches in Git is very easy. Here is the work flow for applying patches using branches.
CLI[edit]
- Create a new branch:
git branch issue-123
(creates a new branch called issue-123). - Apply the patch as shown earlier.
- Commit the code change to the branch:
commit -a
. Now git will open the editor you chose when you installed git. Enter the commit message in the first line of the editor and save and exit. (If you are unfamiliar with the editor, you can either change the editor or use Eclipse, which bypasses this step in the process.) The commit message should be something short that tells you what you did, for example "Applied patch 123.patch"). OR You can commit the code change to the branch wihtout opening editor usingcommit -a -m "<type_your_message_here>"
- At this point, the branch contains the modified version of the Joomla files for you to test. You can easily switch back to the standard files with the command:
git checkout master
. To switch back to the modified version, use the command:git checkout issue-123
.
Eclipse[edit]
- Create a new branch: Team→Switch To→New Branch. The Create a new branch window will show. Enter the name of the branch and click on Finish.
- Apply the patch as shown earlier.
- Commit the code change: Team→Commit. The Commit Changes window will show. Enter the commit message as shown in the example below. At this point, you can review the code changes or simply press the Commit button to commit the changes.
- To switch back to master or any other branch, again use Team→Switch To and select master or the desired branch.
TortoiseGit[edit]
- Create a new branch: Right-click on the project folder and select TortoiseGit→Create Branch, as shown below.
- The following screen will show.
- Enter the name of the new branch in Branch and press OK. Note that this also switches you to the new branch.
- Apply the patch as shown earlier.
- Commit the code change: Right-click on project folder, then Git Commit -> <your branch> as shown here.
- Enter a commit message, check that you are in the right branch, and press OK, as shown here.
- The system will show a success message as shown here.
Restore to Unmodified State (Without Branches)[edit]
If you are not using branches, when you are done testing an issue, you will need to restore your programs to the original unmodified state. Note that this is not needed if you are using branches.
CLI[edit]
- Use this command to undo any file changes:
git reset --hard origin/master
. If it doesn't work, you can usegit apply -R <file>
to the state before the patch was applied. For example,git apply -R folder/file.diff
. - Use this command to delete any new files added by the patch:
git clean -f -d
- This removes added files and directories.
- Run the command: git status and make sure it says "nothing to commit (working directory clean)".
Eclipse[edit]
- Use this command to undo any file changes: Team→Reset to show the Reset window. Select "Hard" for the Reset type and click on Reset.
- To remove any new files added by a patch, simple navigate to the files and delete them.
TortoiseGit[edit]
- Use this command to undo any file changes: TortoiseGit→Revert.
- Use this command to delete any new files: TortoiseGit→Clean up. The system will show a success window and the files that were deleted as follows.
Restore to Unmodified State With Branches[edit]
If you use branches, it is much easier to switch back to the unmodified programs. You simply change back to the master branch. Once you are done with an issue, you will likely want to delete the branch you created. Here are the commands for that.
CLI[edit]
- Change back to the master branch:
git checkout master
- Delete the desired branch:
git branch -D issue-123
(where issue-123 is the branch name)
Eclipse[edit]
- Change back to the master branch: Team→Switch to→master.
- Delete the desired branch: Team→Advanced→Delete Branch and select the desired branch to delete.
TortoiseGit[edit]
- Change back to the master branch: TortoiseGit→Switch/Checkout.
- Select master as shown here.
- Delete the desired branch:
Testing Older Versions of Trunk[edit]
At times, it is helpful to figure out which commit might have introduced a new issue. With Git it is easy to restore the code base to any point in time and then test whether an issue was present or not. Note that this is more difficult with the CLI version.
CLI[edit]
- Write some past commits to a temporary file. For example:
git log --since="2 weeks ago" --mylogfile.txt
- Find the commit id of the desired date. Note that we only need the first 8 characters of the commit id.
- Checkout the desired commit:
git checkout <id>
(for example:git checkout ba574af0
). - See the command reference for git bisect for a more advanced way to find which commit caused a bug.
Eclipse[edit]
- Open the History View: Team→Show in History. This will show a view similar to this:This view shows every commit to the CMS repository. To restore your local files to a prior time, right click on the desired row in the history view and select Checkout. Your local files will be changed to the state as of that commit. You can now test that version.
- To change to a different version, repeat this process. To change back to the master branch (the latest version), do Team→Switch to→Master.
TortoiseGit[edit]
- Open the Log window. TortoiseGit→Show Log as shown here.
- Right-click on the desired commit in the log listing and select Switch/Checkout to this... as shown here. You can now test that version.
- To change to a different version, repeat this process. To change back to the master branch (the latest version), do TortoiseGit→Switch/Checkout and select master.