To create your fork of the MODX repository, go to GitHub and log in (if necessary). Once you are logged in, type http: //github. com/modxcms/revolution in the browser’s address window. That should take you to the MODX Revolution repository. Once there, click on the
“Fork” button. GitHub will create a personal copy of the MODX repository (called a “fork”).
When the fork process has finished, you’ll be back at your own repository and you should
the “Switch Branches” menu item to see the current branches in the repository. Switch to the develop branch. You might be tempted to download the source now from the GitHub page, but don’t do it. We’ll use the Git Bash window to clone your fork so that the files will be under Git control.
We’ll assume that you want to create a local copy of the development version of MODX in your XAMPP/htdocs/modx/ directory. Open up the Git Bash command-line tool and navigate to the htdocs/ directory with a command like this:
cd c:/xampp/htdocs
Be sure you see the path to the htdocs/ directory on the right side of the command prompt before proceeding.
If (and only if) you are on a Windows machine, type the following command in the Git Bash window:
git config --global core.autocrlf true
That will set up the proper line-ending operations so that your files won’t cause trouble when merged with those of users on different platforms. This is very important because the line endings will affect the SHA1 values for every commit. If they are not correct, it can create serious problems for the core developers.
Next, make sure you are in the directory above the directory were you want to install MODX (htdocs/ for most localhost installs). Enter the following command to clone the contents of the MODX repository to the modx/ directory:
git clone [email protected]-.yourGitUsernameHere/revolution.git modx
The cloning will take a while, and you should see progress messages along the way. If you’re denied access, make sure your username is spelled exactly as it was in the Hello Username message you saw when testing with the SSH command earlier — the username is case- sensitive. When the process is finished, switch to the modx/ directory with this command:
cd modx
You should see a prompt for the modx/ directory showing that you are on the (m aster) branch. Type g i t s ta tu s in the Git Bash window. You should see a message telling you that your working directory is clean.
Now, set up a remote that points to the MODX repository:
git remote add upstream http://github.com/modxcms/revolution.git
A remote is simply a reference to a repository somewhere else. It saves having to type in the whole URL every time you interact with the remote repository. The line above sets up a remote called upstream that points to the MODX repository. There is already a remote called o rig in that points to your fork (which was created automatically when you cloned the fork). If you type this command:
git remote -v
you should see your two remotes: o rig in (your fork) and upstream (the M O D X reposi
tory) and the paths to them. The - v switch tells Git to give you a “verbose” response.
Your local files now match the latest stable version of MODX (the master branch of the MODX repository). You need to make your files match the develop branch. Make sure you are in the modx/ directory and issue these commands in the Git Bash window:
git fetch upstream
git checkout -b develop upstream/develop
The first line above fetches all the branches from the MODX repository and creates what’s called a local tracking branch for each of them. The tracking branches simply track the branches at the upstream repository. They always have a slash in their names, and the part after the slash is the name of the upstream branch. Whenever you “fetch” from the upstream repository, they will be updated to match the current state of the upstream branches. Never checkout (switch to) a tracking branch or make any changes to it except by fetching from the upstream repository.
The second line in the code above tells Git that you want to create and switch to a new branch called develop based on the files in the upstream/develop tracking branch.
You should see messages telling you that Git is now aware of some new branches after the first command. It will list all the tracking branches created from the branches at the
upstream repository. After the second command, it should tell you that it has created a develop branch (a local branch) for you that tracks changes at the M O D X repository’s develop branch and has switched you to that branch:
Branch develop set up to track remote branch develop from upstream.
Switched to a new branch: 'develop'
Be sure to read the information in the following section on Git Contributor Workflow so that you don’t accidentally revert your local files to a non-development version or make undesired changes to them.
If you look at the local files on your computer, you might expect to see all the branches Git just created. In fact, none of them will be visible. You'll just see one set of the MODX files. That's because you can only have one branch checked out at a time. The other branches exist, and Git knows about them, but you'll only see the files from the branch you currently have checked out.
When you check out a branch, Git changes all the files to match those of that branch. The set of files you see is usually referred to as the 'working directory."
Be careful not to switch branches while you have unsaved files in your editor or else you can end up with a real mess.
Now, update your local files from the M O D X repository (upstream) just in case any commits have come in since you created your develop branch:
git fetch upstream develop
git merge --ff-only upstream/develop
The first command above updates the upstream/develop tracking branch. The second command above tells Git to merge any changes in the upstream/develop tracking branch into the current branch (develop). Note that the - -ff-o n ly option has two hyphens at the beginning. It tells Git to use a “fast forward” merge, which will automatically abort the merge if there are any merge conflicts. Conflicts will only occur if you modify tracked files in the local develop branch — something you should never do.
At this point, you can build and install a working version of M O D X . See the sections below on how to do that.
Your local master branch is no longer of any use to you if you intend to work from the develop branch. You may want to keep it there for reference, but you may also want to delete it to prevent you from accidentally using it. To delete it, make sure you are on your develop branch (git checkout develop) and then issue this command in Git Bash:
git branch -D master
To prevent other kinds of confusion, you may also want to remove the rest of the local branches except develop, upstream/develop, and some of the branches at your fork. You can see the local branches with this command:
git branch
You can delete them as you did the master branch. You can see the branches at the remote repositories with this command:
git branch -r
That will show you the branches at the MODX repository (upstream) and the branches at your fork (origin). To delete a remote branch at your fork, issue this somewhat cryptic command:
git push origin :branchName
The colon in this command separates the source from the destination (source: destination).
Since there is nothing on the left side of the colon, it tells Git to push “nothing” to the remote branch, which deletes the remote branch.
You can actually delete all of the branches at your fork (although GitHub will refuse to delete the current branch there — usually the master branch) since you should never be fetching anything from your fork. You’ll do your work in a local branch you create just for a specific bug-fix or feature, and you’ll push that branch to your fork. None of the other branches there are necessary. The only reason the fork exists is to hold branches that you issue pull requests for so that the MODX team can merge your changes into the MODX repository.
You might expect that your fork at GitHub will be updated automatically to t l match the MODX repository you forked it from. This is not the case, however.
That means that your fork will quickly be completely out of date, which is why you never want to fetch from it. The only reason the fork is there is so that you can push changes to it that you want to contribute to MODX.
At this point, your local develop branch matches the MODX repository’s develop branch.
You can now build and install MODX using the steps outlined in the sections below on Building the Transport Package and Running Setup, but be sure that you are on your develop branch (g it checkout develop) before doing so.
Working in the MODX Manager won’t affect any of the files that Git tracks in your local installation, so feel free to do anything you want in the Manager as long as you don’t go to the Files tab and edit any of the MODX core files — something you should only do if you want to fix a bug in the core and contribute it to MODX.