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!
you have sitemap.xml twice in your final gitignore
What if we try to ignore all files in wp-content, except for themes and plugins?
wp-content/*
!wp-content/plugins/
!wp-content/themes/
Greetings from Brazil!
Really helpful, thanks!
How does it work when upgrading the core or plugins via the admin area? Since the core is under version control should all updates been done on development and pushed to production?
Hi Ben,
Opinions differ on whether or not you should version control the core. Personally, I do – I test all updates and upgrades on my local dev, push them and then pull them to live all at once. Quickest way to launch a bunch of updates.
True, but then how do you manage the database changes that may occur with a plugin update?
It’s never been a problem for me, as I take a copy of the very latest live DB to run the test updates/upgrade on locally.
Providing that works okay and everything tests fine throughout the site, I commit and push to the GitHub repo, wait for a quiet time on the live site, pull the latest code in and visit the WP admin – that kicks off any DB upgrades necessary with the latest plugins.
Of course, this does rely on your local dev being a carbon copy of live so you can be sure that you won’t encounter problems that didn’t occur locally, but these days that’s relatively easy to achieve using Virtual Box and Vagrant. I use Varying Vagrant Vagrants myself as our live server is NGINX, but it’s just as easy to grab a LAMP stack and tailor to match your live environment too.
Hi thanks for this.
Why is .htaccess in the original list but not in your edited list? What is your thinking? It seems that it is a good candidate to leave off, unless there is something very special configured.
Thank you
suggested to add — desktop.ini (for those of us working in a windows environment.