Using Git in a WordPress Development Workflow
There’s a number of different ways you could use Git in your WordPress development workflow. That’s one of the beautiful things about Git – it works well with almost any workflow including different types of WordPress development flows.
You might be working on a single theme, a plugin or you could be working with an entire WordPress installation. It doesn’t matter because you can use Git in any of those scenarios.
Getting Git on Your Computer
Git is an open-source source code management system. It’s often referred to as a version control system which is also an accurate description. Written in C code so it can run on the majority of systems. You can download an installer for your OS on this page: Git Download.
If your using a Linux based OS then you can use your package manager to get it. On Ubuntu you would type this into a terminal.
apt-get install git
Other package managers use slightly different syntax – Redhad based distros use
yum install git – and if your on Windows or Mac then you’ll need to run through an installer installer.
Note that Git comes with an built-in GUI but it’s probably not going to be user friendly enough for a new user. If your in that situation I suggest that you make use of the GitHub client which is a nice GUI. It can be used for pushing to repos that aren’t hosted on GitHub so don’t worry if you don’t plan on hosting your code there.
Other ways to Get Git
Git is bundled with many packages and software so it may already be installed on your system. If not you can install the GitHub Client that’ll handle installation of Git for you.
Some Basic Git Commands to Know
There’s a few commands that you should know the basics about before you start working with Git and WordPress – or any code for that matter. You can get the complete documentation online on the same site you downloaded Git from – or you can use the man pages or
--help from the command line. Example:
git clone --help to get help for the clone command.
git clone <repo>: This command is used to clone a repo into the directory you run the command from. If you were wanting to clone WordPress Core from GitHub you would run this command:
git clone https://github.com/WordPress/WordPress.git. Note that when you clone a repo it downloads the code into a folder that’s the same name as the repo – so cloning WordPress will put it inside a folder called WordPress.
git init: This is the command you use to initialize a repo in a specific directory.
git add <file>: This adds a specific file (actually it adds incremental changes) to the staging area of your current branch. You can use
git add ./to add all the files/changes in a directory to the staging area.
git push <remote> <branch>: This command pushes the currently staged code in a specific <branch> to the specified <remote>. Generally you’ll see the command be used like this:
git push origin master
git commit -m "<message>": Commit changes in the staging area to the HEAD ready to be pushed to the hosted Git server (or wherever else you were pushing to). The -m flag allows you to include a commit message along with the changes which you should usually do.
What Some of the Terms Used there Mean
- Repo – This stands for repository. It’s the directory that the code (and the subsequent .git directory) is contained in.
- Branch – A branch is the name given to a specific version of your code. Say you were working on 2 different new features at the same time – you would do that in 2 separate branches that keep the code for each of them isolated. Branching is one of the most powerful things about Git.
- Remote: – A remote is a remote location outside of your current working directory that you want to send your code/changes to. Commonly remotes are hosted Git servers but they can be arbitrary locations on your filesystem or other on a different machine.
- HEAD – This is a pointer that tells Git what branch your working in or what revision is in your working directory.
Starting a new Plugin or Theme
To get started let’s take a look at how you would use Git to manage a WordPress plugin’s code.
When your starting work on a new WordPress plugin or theme using Git you would do it just the same way as you would without using Git – making a folder for the files. To start off it’s just an ordinary folder, nothing special about it. You can make it by right clicking and choosing to create a new folder or you could do it via command line if you wanted. On *nix systems the command you want is
mkdir <folder name>. After you’ve made the directory you need to initialize the repo with
mkdir my-new-plugin cd my-new-plugin # to move to the new direcotry git init
Once you’ve initialized the repo you can start adding your files and code.
Quite often people like to make an initial commit before they start to work. That can be done by making a single file, adding a remote then pushing to the hosted directory. We’ll take a closer look at doing that a little later in the article.
There’s no special way to write code in a git repo, write it however you would normally. Assuming your plugin only has a single file called my-new-plugin.php this is how you would add it to the staging area.
git add my-new-plugin.php
If your plugin had more than a single file then adding each of them individually might be quite cumbersome. That can be done like this:
git add ./
After adding the files to the staging area the final step is to commit the changes.
git commit -m "initial commit"
Replace ‘initial commit’ with some descriptive text about your change that describes the change quickly.
You can make, stage and commit as many files or changes as you like. It’s recommend to commit often so it’s easier to follow along with the full change-set for your code.
In a simple plugin with just 1 file (or a handful of them) it might seem like overkill to commit so often so let’s take a look at how you would do this with something a little more complicated like a theme.
mkdir my-new-theme git init # add your theme files/code to the directory git add ./ git commit -m "commit message" # make some changes to the code git add ./ git commit - "another commit"
See how it works basically the same as it would if you were making a plugin with a single file? That’s because Git scales with ease – from a single file through to dozens of files or even to thousands or millions of them.
Most projects contain several directories. A simple example is storing the main files in the root of the directory and then having more directories inside the root for things like the css, js folders. Those get included when you run
git add ./ so there’s nothing special you need to do to add those.
Hosting Your Repo on a Git Server
It’s all well and good to keep a version controlled plugin on your local machine but it works best when you distribute your code so that it can be cloned into other locations. The most well known is GitHub.
The Standard GitHub is for open-source code only so bear that in mind if your sharing something there. If your not wanting to open-source your code then you can signup and pay a small fee (just $7 for bottom tier) to get some private repos. Github Enterprise is available as well if your a large company.
Another option for a host is BitBucket. They allow unlimited private repos for up to 5 users.
My personal choice for a Git Server is GitLab. It’s a self-hosted Git server coded in Ruby-on-Rails that’s limited only by the size of server you run it on. You can get your own GitLab server up and running quick and easy using a VPS from Digital Ocean and their pre-made deploy images.
Some options for hosted Git repos:
- GitHub – Free for public repos, affordable private ones.
- BitBucket – Free for public and private repos with up to 5 team members working on them.
- GitLab – Free for public and private repos. You can use their service or you can install the self-hosted open source software – the only cost is the server it runs on if your self-hosting.
SSH keys for Working With Git
No matter which service you sign-up to your going to need to use SSH keys to authenticate and prove you have the right to access the hosted repos. If you already have an SSH key that you want to use then just copy it from your computer and add it to their systems. If you don’t already have one then you’ll need to generate a new key.
You do that with the ssh-keygen command. Github has a great article on generating keys and installing them on a server so have a read of that.
Once you’ve signed up at one of those services (or rolled your own with GitLab) and added your Key you need to make a new repo in your account. You can do it through the GitHub or BitBucket client software if your using their system to host but I tend to do it through the web interface.
Once you have a hosted repo set-up the next thing to do is add the endpoint – the remote – to your local repo using
git remote add <name-of-remote> <address-of-repo> – the name of the remote is whatever you choose to call it. The default name of the first remote is ‘origin’ because that’s usually the origin of the code whenever anyone else uses it. The address of the repo will be a url that looks like this for an https one: https://github.com/pattonwebz/repo.git or this if it’s an SSH one: firstname.lastname@example.org:pattonwebz/repo.git. An entire command to add a remote would look like this:
git remote add origin email@example.com:pattonwebz/repo.git (the example uses an SSH url but could also use the https version).
Examples of How to use Git in WordPress Development
There’s a number of different ways to use Git in a WP workflow but I’ll list out a few ideas that will be useful. I’ll start with some simple examples and then move on to some more that will help save you time and energy while working on a project.
To Manage the Code of a Theme or Plugin
I detailed this a bit earlier in the article. Essentially you would use
git init in the directory of your plugin or theme to initialize the repo and commit changes as you made them. Pushing the repo to a hosted Git server could be done whenever you chose to. You can start management of the code at any point – so you can start with a brand new project or you can begin tracking an existing project.
From the directory your files are stored in:
git init git add ./ git commit -m "<commit message>" # repeat the add-commit cycle as many times as you require git remote add origin <url-of-repo> git push origin master
Once you have the final version of your plugin ready (and on a Git server) you can visit the plugins or themes directory of the WP installation and clone your project into it.
git clone <url-of-repo>
To Deploy a Theme or Plugin
Many common plugins are already hosted on GitHub. You can clone them directly into a site’s wp-content folder with a single command.
git clone <url-of-repo> – this command will clone the code of the plugin into the folder the command is run from. You should run inside the plugin directory or the theme directory depending on what your installing.
For example if you wanted to clone Yoast’s SEO for WordPress plugin you could do it with this command:
git clone https://github.com/Yoast/wordpress-seo.git. Issue this from inside the plugins directory and it’ll install it for you.
To Install a Collection of Plugins at Once
If you commonly use the same collection of core plugins on all the sites you build you could create a repo containing them all and clone the repo to install them in just a handful of commands.
Creating the Repo with the Plugins
Start by creating a repo at your Git server then download all the plugins you want to have in it. Unzip them into a folder.
Go to the folder and run this set of commands:
git init git add ./ git commit -m "initial commit" git remote add origin <url-of-repo> # you can add the remote at any point after initializing git push origin master
Installing the Plugins to wp-content
Now that you have all the plugins you want to install in a git repo that you can access from anywhere the next time you start building a site it’s just a case of getting them into the plugins folder.
If the plugin folder is empty you can simply clone your repo into that directory by going to the wp-content folder and using this command:
git clone <url-of-repo> plugins
Usually the plugins folder isn’t empty – it has existing plugins in there like Akismet, Hello Dolly, the index.php file and any others that have been installed so this is a little more complicated that simply cloning your repo – because your not allowed to clone into a directory that has existing files or directories. Luckily you can get around that by using fetch instead of clone as per this answer on stack overflow.
Go to the wp-content/plugins directory on the site you want to add files to and run these commands.
git init git remote add <url-of-repo> git fetch origin master git checkout --track origin/master
Git will create a new repo for the whole plugins folder, fetch your plugins from the hosted repo an place them into the folder – while keeping the existing plugins in the directory intact. You can then activate the new plugins from within the dashboard – no need to install each one separately or manually upload them all.
Managing the Code of an Entire Site
When I’m working on a new site I keep the code for it versioned in a Git repo. Doing this you have a choice to make regarding verioning the WordPress Core files. Do you version them or not?
I tend not to version the core files because I prefer to keep the core fully updated. An exception to the rule would be when a core version change might interfere with the ability of certain plugins or functions that are in the repo working.
Ordinarily you don’t need to version WP core, however it’s easier to do it by versioning the whole thing so let’s look at how to do that first.
It’s worth noting that there are some directories and files that you wouldn’t want to include in a full site repo. Some of the directories would bloat your repo considerably while others would pose a security risk. You can omit the unwanted WordPress files and directories by using a
.gitignore file. The default
.gitignore file I use is adapted from the one that WP Engine provides on their Git page. I’ll be providing my version below.
The directories that should be excluded are the uploads and upgrade directories as well as a few others that contain a large number of files not needed for a site’s operation (such as a cache storage directory). There’s one specific file that should never be included for security reasons. That’s the wp-config.php file. That file contains confidential information such as the database server access credentials as well as your site’s salts.
Those directories (and the wp-config.php file) are excluded from being uploaded thanks to the .gitignore file.
Versioning a Site Including WordPress Core
Navigate to the rood directory of your WordPress installation and initiate the repo, add the .gitignore file (get that here and rename it to .gitignore) to the directory. After then add the files from your WP install to the Git staging area and make the initial commit:
git init git add ./ git commit -m "initial commit"
Make any adjustments as necessary, add a remote and push it to your hosted Git server. You can then deploy it using a clone command the same way you would with any other Git repo.
When I’m working with full sites I like to automate the deploy process using a webhook. I’ll be talking about automated deploys in another article because it’s a lot to cover but the deploy script I use is adapted from this really nice script here: Simple-PHP-Git-Deploy Script.
Versioning a Site Excluding WordPerss Core Files
Excluding all of the WordPress core files can be done using an extended .gitignore file based on the one linked above. Here’s the version that excludes the full WP Core.
Git can be used in all kinds of workflows and for all kinds of tasks. I’ve only just scratched the surface of what’s possible here but hopefully I’ve given you a few ideas of how you could use it to improve your workflow or make your life a little easier.
If you have any questions or suggestions of how else to use Git please leave them in the comments below and I’ll get back to you ASAP. Or you could email me using the form on my contact page.