You now have a local copy of the development version of MODX. You can use Git fetch and Git merge as we did just above to get changes other people make to the MODX repository into your local copy to keep it up-to-date. When you make changes locally to fix bugs in MODX, you can use Git push to send them to your fork, but always be sure that you make your changes in a local branch you create just for your own work. You want to make sure your local develop branch always matches the MODX repository’s develop branch, so never edit, delete, or rename files while on your develop branch.
The following guidelines are critical in order to keep things from blowing up in your face.
They are especially important if your understanding of Git is less than perfect:
« Always fetch from the develop branch of the MODX repository at GitHub while on your develop branch. In other words, whenever you want to get updates from the MODX repository (and you should do this often), make sure you are in your develop branch. To update, use the following commands:
git checkout develop git fetch upstream develop
git merge --ff-only upstream/develop
« Avoid typing g it fetch by itself or else you’ll get back all the branches you deleted.
This won’t hurt anything, but it wastes disk space.
■ When you fetch changes, you may see [ReUp] or [Rebuild Upgrade] in the commit messages (always look to see if one of these appears). That message means that you need to re-run the build and Setup steps described in the following sections before logging
in to your MODX install. Failing to do so can trash your MODX install. I generally run a build and Setup whenever I update just to be on the safe side.
Never modify any local files in your develop branch. It should always match the develop branch at the M O D X repository (upstream).
When you make changes in a local branch you’ve created, never merge them into the develop branch. If you submit a pull request and it is accepted, you’ll get the changes when you update from the MODX repository.
Always push your local bug-fix branches to the origin remote (your fork). Pushes to the MODX repository (upstream) will be rejected automatically. There is no need to keep the develop branch (or any other branches) at your fork up-to-date.
Let’s work through an example that shows how to contribute a bug-fix or minor improve
ment to MODX. When you want to fix a bug in MODX and contribute your fix to the project, always follow these steps:
1. Update your develop branch just before creating a new work branch:
git checkout develop git fetch upstream develop
git merge --ff-only upstream/develop
2. Create a branch to work in. We’ll use the name bugfix in our examples, but you should use a descriptive name for your branch so that you and the MODX core developers will know which bug it fixes:
git checkout -b bugfix
3. Edit files and fix the bug. Then commit your changes to your bugfix branch. Be sure to enter a brief but clear commit message describing what you’ve done:
git commit -a -m "Your Commit Message"
4. When you are ready to submit your code, always update your bugfix branch from the MODX repository just before pushing it to your fork with these commands (while on your bugfix branch):
git fetch upstream develop git rebase upstream/develop
The rebase command, which we haven’t seen before, is a special kind of merge that tacks your local changes onto the end of all the other changes in the merge. In the rare case that
the rebase fails, it means that someone else has modified at least one of the files you changed since you created your bugfix branch. If this happens, you need to save your changes some
where outside the working directory, delete your bugfix branch, and start over from step 1.
5. Push your changes to a bugfix branch at your fork:
g it push origin bugfix
6. Now, go to your repository at GitHub and switch to your bugfix branch by clicking on the
“Switch Branches” menu item. Click on the “Pull Request” button. Notice that the message there says that you’re asking for your commit to be pulled into the modxcms: master branch from your bugfix branch. You don’t want that because all pull requests for the MODX master branch are ignored. Click on “modxcms: master” and on the left side of the screen, change master to develop. Click on the “Update Commit Range” message. Make sure that modxcms: develop appears in the top line and that the commit will be pulled from your bugfix branch. Now enter a message describing what your change does in the empty form field and click on the “Send Pull Request” button.
When you perform a commit in Git Bash, you can use -m "message" to specify the commit message. If you leave it out, Git Bash will launch the Vim editor by default. Beginners usually feel trapped in Vim because it's not at all obvious what to do. If you find yourself in Vim, this should help:
Type the letter i to go into insert mode.
Type your message.
Press the escape key to go into command mode.
Type :wq to save and exit.
You can also configure Git to use the editor of your choice by editing the users/your username/.gitconfig file. Add a line like the following one con
taining the path to your editor in the [core] section of the file:
editor = "’c:/Program Files/Windows NT/accessories/wordpad.exe’"
Create a new branch for each bug you want to fix, fix a single bug on each branch, and never merge changes from one branch to another. If you need to make local changes to
and never issue a pull request for that branch. Branching is “cheap” in Git, and you can create a new branch for everything you want to try. Pull changes at the MODX repository into your branch the same way you did it for your develop branch:
git fetch upstream develop
git merge --ff-only upstream/develop
If your changes on a branch don’t work out, it’s easy to delete the branch. Be sure you’re not on the branch that you intend to delete. (If you try to delete a branch you are currendy on, Git will tell you that can’t do it.) Use these commands:
git checkout develop git branch -D branchName
To delete a branch on your remote fork of MODX, use the command we describe earlier:
g it push origin :branchName
Important: Never delete a branch at your fork while there is an open pull request for commits on that branch.
Although it’s easy enough to work in separate branches in Git, some people prefer to keep a separate copy of MODX in a different directory for changes that they never intend to share. This prevents any possibility of accidentally merging changes.
As we mentioned earlier, you should never merge your own changes into your develop branch. The reason is that the next time you fetch from the MODX repository, Git will undo all your changes. If your pull request is honored, the changes will appear in the MODX repository and you’ll get them when you fetch from it.