Since starting to use GitHub for version control a couple of years ago, I love the flexibility it offers. But what should you exclude from Git version control in a WordPress project?
Git allows you to add any files you want to ignore to a file in the root of the project to a file called .gitignore. GitHub has a default WordPress gitignore file, which is a great start:
.htaccess .htaccess wp-config.php wp-content/uploads/ wp-content/blogs.dir/ wp-content/upgrade/ wp-content/backup-db/ wp-content/advanced-cache.php wp-content/wp-cache-config.php sitemap.xml *.log wp-content/cache/ wp-content/backups/ sitemap.xml sitemap.xml.gz .DS_Store
Let’s step over this to explain the logic.
Configuration files are specific
Broadly speaking, you always want to avoid including any configuration files in a repository, as chances are the settings on your local development environment aren’t the same as your live site, and you might have multiple developers using their own settings and development environments. As WordPress holds all configuration in the wp-config.php file, we exclude that in our WordPress gitignore. Each developer then has to create their own version, and a live version is created at launch.
Media and images
If you’re working with other developers with their own development environments, the way that WordPress stores images and media in general poses a bit of a problem. WordPress stores all uploaded images in the wp-content/uploads folder in sub-folders for each month. It also stores a unique reference to the uploaded image in the WordPress database.
The problem is that when you’re working with other developers, they’ll all have their own copies of the site database, so if you upload an image to your local development version and then commit it to the Git repository, the next time another developer pulls the repository they’ll have an orphaned image in their wp-content/uploads folder without an reference in their database. Not good. To avoid this we keep the entire uploads directory out of version control.
Caching, sitemaps and log files
There’s absolutely no need to version control cache files, sitemaps or log files – they’re all related to the specific install of WordPress you’re working on and there’s no need to share them with other project developers, so we leave these out too. The GitHub .gitignore file ignores some specific files that created by popular WordPress caching and sitemap plugins.
Some additions and improvements
Our WordPress hosting provider, WPEngine recommends to add a few more exclusions to the .gitignore files;
- .DS_Store files generated by Mac OSX at the root of every folder and are redundant for anything else, so we remove them.
- .svn and .cvs belong to other Subversion and CVS version control systems that may have been historically used on the project.
Should you version WordPress core?
A good question. In theory, you probably shouldn’t as it’s never necessary to change the WordPress core code when developing your project. As a result those files don’t change, so there’s little need to version them. In practise though it depends on your setup. As WordPress updates every 3-4 months and it’s very important to keep it up-to-date for security reasons, you’ll probably find it better to keep the core files in Git – that way if a new developer pulls the repository to work on they’ll have the correct core code in place.
Our final WordPress gitignore file
*~ .DS_Store .svn .cvs *.bak *.swp Thumbs.db wp-config.php wp-content/uploads/ wp-content/blogs.dir/ wp-content/upgrade/ wp-content/backup-db/ wp-content/advanced-cache.php wp-content/wp-cache-config.php wp-content/cache/* wp-content/cache/supercache/* *.log wp-content/cache/ wp-content/backups/ sitemap.xml sitemap.xml.gz
Hope that’s a helpful place to start when using Git on a WordPress development project!