Development Environment

Setting Up Projects on Localhost With Git

gourmet fare

Git Ignore on Localhost

When you're developing an extra on a localhost installation, how can you set up your .gitignore to ignore your core but not your extra's files?

OptimusCrime asked...

I am developing an extra and I am having a terrible time trying to cope with ignoring the correct directories etc to make everything work. To avoid including some of Modx's core I ignore the core and assets directories, and this of course makes life difficult when I try to unignore the subdirectories for the extra. So my question is rather simple. I've seen people talk about their development setup, but no-one (as far as I can tell) has in details shared how to do this the "right" way.

The Solution:

BobRay says...

I put all projects under assets/mycomponents/projectname. They're all inside the same MODX install.

Each project has its own local git repository, created by navigating to the project directory and doing "git init". I have a set of aliases in the .bash_profile file in my user directory that let me go to a project directory. For example, this lets me jump to the NewsPublisher project by typing "np":

alias np="cd /c/xampp/htdocs/addons/assets/mycomponents/newspublisher"

Keeping things organized

If there's anything in the project that should be ignored, you can create a local .gitignore or .git/info/excludes file. The advantage of the latter is that Git ignores the .git directory automatically so you can change the excludes file whenever you like without the changes showing up in Git status.

The down side of this is that you can't use Git to update MODX itself or to issue pull requests. You can, however, use the install.php script to update MODX or just download and unzip the files, and you can run setup as you normally would.

The up side is that I can search all of MODX and/or all of my projects when looking for something. PhpStorm indexes the whole thing, so the search is fairly fast and I can jump instantly to the declaration of any method or function by putting the cursor on the name and pressing Ctrl-B, regardless of whether the target is in my code, xPDO or MODX. After looking at the function code, Ctrl-Alt-left-arrow will take me back to where I came from.

MyComponent, BTW, will set the whole project up for you (minus the "Git init") in assets/mycomponents. You just have to edit the one config file and run bootstrap.

What's the Story?

Setting up a localhost environment for developing extras requires careful thought as to where everything goes. As BobRay says in his solution, his MyComponent extra sets everything up for you once you customize its configuration file and run its bootstrap script, so then all you need to do is create your git project for each component. And if you do need to update your localhost installation, you can use BobRay's UpgradeMODX Dashboard widget to install the latest version and run setup with one click.

It may seem a bit unintuitive at first to have all of your project's files in assets/components/, but MyComponent takes care of packaging them so that on installation of your package the files will go to core/components/ as usual. Having the files all in one place for development actually simplifies the development process considerably, as well as making it a lot less troublesome to set up your project's git repository.