Using Git with DreamPress

It's a common desire to customize a WordPress site to your own personal look and feel. However, a major problem with customized theme code is that when the developer updates the theme, your customizations are overridden. A solution to this problem is to create a child theme with Git version control.

Creating a child theme usually requires using something such as the Google browser developer tools to find out what changes you need to make to the theme’s CSS stylesheet. You also might need to make changes to one or more of the PHP files to update specific WordPress templates.

Keeping track of multiple changes like this can quickly become tedious and confusing. Additionally, how can you test new changes without losing current changes and how do you go back to a change you previously made if you find you made a mistake? Once again, the best solution is to use Git version control with DreamPress.

Git is a versioning control system that allows you to keep track of every change you make to your site. It is ideal for creating and maintaining themes, plugins, and any customizations to your WordPress website beyond those you can make in the dashboard. As a version control tool, Git allows you to take snapshots of your code so that you can retrieve a backup at any time. Git also allows you to create a “branch” to add a new feature, fix a bug, or even experiment with new changes without worrying about messing up the current version.

In the past, you would use FTP/SFTP to update your website. However, a major problem with these protocols is that you cannot go back to an earlier version of your customizations in cases such as when a change breaks your site. You also can’t review an earlier version to see what did change. These issues are solved by using Git.

Git is commonly used with SSH and a terminal when creating remote repositories. However, there are also some good GUI Git applications that can be used. Two good ones are SourceTree and Tower ($$).

Using Git for custom themes or plugins allows you to share them between websites or with other users. If you choose to do this it's highly recommended to put each project (theme or plugin) in its own repository. Doing so will allow you and others to easily keep track of your custom work.

It's not recommended to use Git as a WordPress backup tool. For example, there is no need to put your instance of WordPress under version control. That is already done by the WordPress core developers. Also, if you had your entire site under Git version control, everything would get overwritten during a WordPress auto-update. Rather, think of Git as a tool to manage your customizations or your own theme and plugin development.

Using Git for database version control is also difficult and is not recommended. WordPress already handles version control for posts and pages so this is unnecessary.

There are a few different workflows that can be used with Git and WordPress. What works best depends on if you are jointly developing with others or not, as well as your personal preference.

1. Local only — Only use Git locally (on your computer) and continue to use SFTP to update your server with changes.
2. Local and web server — Create a Git repository both locally (on your computer) and on your web server. Push changes from your local instance to your server instance that is copied to your WordPress theme or plugin directory.
3. Local, public Git host and web server — This configuration is ideal when you are doing joint development with others. You can use GitHub or Bitbucket to host your collaborative development to update and share code changes. And whenever you choose, you can push updates from the Git host to your web server. GitHub is best for code that will be shared publicly while Bitbucket is better for a private repository as it is free. (GitHub charges for private repositories.)

DreamPress has built-in support for Git. It can be used for either the second or third type of workflow shown above. The example below looks at the second workflow method—a local Git repository and one on your DreamPress server that you keep in sync.

Probably the most common use case for using Git is in creating a child theme. Quite often you want to make changes to a theme and not have your changes overwritten when you need to update the theme.

Step 1 — Install Git onto your computer

Git must be installed on your computer so you can run git commands. There is a great article in the online Git documentation that explains how to do that for Windows, Mac OS, and Linux. Note that Git is now installed on Mac OS by default if you are at the latest release. You can check to see if it's installed with this command in the terminal app:

[mycomputer]$ git --version

Step 2 — Create a shell user in the DreamHost panel

Set up a shell user in the DreamHost panel if you haven’t done so already. You can also change the current DreamPress user from a SFTP to a Shell user. View the article on how create a user with Shell access.

After you change the user type, write down your shell username, password, and host (server name). For DreamPress, your username and host look something like this:

Shell username:  wp_ab1cde
Host:  wp_123456.dreamhostps.com

Step 3 — Set up an SSH key on your computer

This allows you to automatically connect to your DreamPress server and enables Git commands to work remotely. This varies a bit between Windows, Mac, and Linux, so check out this help article:

• Setting up an SSH Key for passwordless login

Be sure to copy down your passphrase in a secure place. You may need it (such as for the Mac OS keychain).

Step 4 — Choose your favorite terminal

Windows: You can use the Windows Shell or third-party programs like PuTTY, SuperPutty, and MobaXterm.

Mac OS and Linux: Both Mac and Linux include a terminal, but third-party options are also available. For example, iTerm2 is very popular with Mac.

Open your terminal at this point, which is used from here on out.

Step 5 — Log into your server

Log into your server using SSH. This takes you directly into your shell user root. Using the sample shell user and server, it looks like:

[mycomputer]$ ssh wp_ab1cde@wp_123456.dreamhostps.com

The first time you do this, you must accept your server as a valid host. This information is saved in a known hosts file on your computer. View the following article for information on how to verify the server identity:

• 'The server's host key is unknown' warning

Step 6 — Set up your server Git repo

This does not need to be in the same directory as your child theme, but make sure you remember where you create this directory. This example creates a /git directory under your username, outside of the website directory. Run the following Linux commands to create the directory and initialize the repository on your web server.

1. Run the following commands to create your identity to be used with Git. View the SSH article for details on how to log into your server:

   [server]$ git config --global user.name "John Doe"
   [server]$ git config --global user.email johndoe@example.com
   [server]$ git config --global init.defaultBranch main
   

   The last line ensures newly created repositories use the name main as the primary branch. View the following article for further details:

   • Configure git to use 'main' as the primary branch
2. Make sure you're in your user's directory by running pwd:

   [server]$ pwd
   /home/username/

3. Create the directory in which the repository will be stored. You can name it anything you like. In this example, two directories are created, /git and /projectname:

   [server]$ mkdir -p git/projectname 

4. Change your current directory to the newly created directory:

   [server]$ cd git/projectname

5. Initialize the repository:

   [server]$ git init --bare
   Initialized empty Git repository in /home/username/git/projectname/

6. Be sure to create a directory for every unique project. This helps you to keep track of them in the future.

Step 7 — Create a file to copy updates

This step creates a file to copy updates from your server Git repo to your child theme directory. This example uses a text editor program named nano. View the Creating and editing a file via SSH article for further information on how to edit a file.

1. Make sure you're in your /git/projectname directory.
2. Run nano and create a file named post-receive:

   [server]$ nano hooks/post-receive

3. Add this code to the file, which tells where to push these changes. This must point to your child theme directory.

   In this example, change username to your actual shell user, change example.com to your website, and change child-theme-directory to the name of your child-theme directory.

   #!/bin/sh
   GIT_WORK_TREE=/home/username/example.com/wp-content/themes/child-theme-directory git checkout -f

4. Save and close your file to return to your shell.
5. Give the file execute rights in the terminal command line:

   [server]$ chmod +x hooks/post-receive

Step 8 — Create a child theme

Create a basic child theme. Use the following article for step by step instructions:

• Child Themes

Step 9 — Download your website files to your computer

You should have all of your DreamPress site files on your local computer. If not, download them via SFTP.

Step 10 — Create your local git repository on your computer

1. Make sure you're in your child theme directory:

   [mycomputer]$ cd ~/example.com/wp-content/themes/child-theme-directory

2. Run the following to initialize it:

   [mycomputer]$ git init

Step 11 — Customize your local child theme on your computer

This step is not covered in this article. Check out this blog post on how to create a child theme:

• Child theme handbook

Step 12 — Set up the connection to your remote server

This is done by using a git remote command in your child theme directory.

1. Make sure you're in child theme directory:

   In the following example, the word myserver is just an alias. It can be named anything you want. But this alias name will be used when you push your content in the future.

   [mycomputer]$ git remote add myserver ssh://username@server.dreamhostps.com/~/git/projectname

   The following is how it would appear with a DreamPress user and server:

   [mycomputer]$ git remote add myserver ssh://wp_ab1cde@wp_123456.dreamhostps.com/~/git/projectname

2. Run the following to see if it was correctly added:

   [mycomputer]$ git remote -v

Step 13 — Save your changes

Now that you've customized your child theme, you must save your changes to your local git repo.

1. Add your changes to your local git index:

   [mycomputer]$ git add .

2. Commit these changes, which records the changes to the repository. Include a brief message in the commit command, which is a quick note to remind you of what you're committing. For example, it could be "first commit of child theme":

   [mycomputer]$ git commit -m "message about the commit"

3. Check the status of your git repository by running the following. You can check it at any time:

   [mycomputer]$ git status

Step 14 — Push your changes to your website server

Now that the connection between your local and server git instances is made, you can push your changes to your server repository and your WordPress site:

1. In the child theme directory, run the following command only once:

   [mycomputer]$ git push -u myserver main
   Branch main set up to track remote branch 'main' from 'myserver'

2. Whenever you create a new snapshot in your local git repo, push it to your server simply with this command:

   [mycomputer]$ git push myserver

That’s it! Once you have set this up, it's simple to keep these two repos in sync. You also have all of your child theme development under version control.