Create Customizations with Git

The Git version control system makes it easier to track your own changes and the changes that we make to themes and templates in each WHMCS release. We recommend that you start customizations of our shipped themes and templates by copying the appropriate repository using the method below.

For steps to apply newly-released changes to your cloned theme or template, see Update Customizations with Git.
For more information about Git, see Git’s documentation.

WHMCS’s GitHub Repositories

To help you successfully create and update your own custom system themes and order form templates, WHMCS provides copies of our shipped themes and templates in Git repositories on GitHub™.

GitHub provides line-by-line reports (diffs) on each change to the repository, allowing you to easily understand and apply the changes from each release.
Git’s merge features allow you to quickly add these changes to your custom copy of the repository. Often, you can perform this merge automatically, without the need to manually update your code.

Copy a Theme or Template Repository

The steps below assume that you are already familiar with version control and beginner-level Git commands.
Before you can perform these steps, you must create a GitHub account.

To start customizing a theme or template:

1. Find the desired repository.

To find the repository for your desired system theme or order form template:

Go to the WHMCS GitHub account.
Choose the Repositories tab.
Find and click on the repository in the list. For example, the repository for the Twenty-One system theme is templates-twenty-one.

2. Check out a local copy of the repository.

Create your own local copy of the repository. This copy will become your customized version of that theme or template.

To do this, copy the clone URL and run the appropriate git clone command.

For example, the following command clones the Twenty-One theme’s repository to the local custom-theme-name directory:

git clone [email protected]:WHMCS/templates-twenty-one.git custom-theme-name

You will see output that is similar to the following example:

Cloning into 'custom-theme-name'...
remote: Counting objects: 261, done.
remote: Total 261 (delta 0), reused 0 (delta 0), pack-reused 261
Receiving objects: 100% (261/261), 273.33 KiB | 0 bytes/s, done.
Resolving deltas: 100% (121/121), done.
Checking connectivity... done.

For more information, see Cloning a repository.

3. Verify that you successfully cloned the repository.

Check to ensure that the repository cloned correctly into your specified directory.

To do this, you can run the following commands:

git status

To check the status of your local repository and branch, run the git status command.

You will see output that is similar to the following example:

On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

For more information, see git-status.

git log

To list the changes included in the cloned repository, run the git log command.

Git will list each commit in the repository’s main branch, from newest to oldest.

For more information, see git-log.

4. Apply your customizations.

Customize the template files or copy existing customizations into them.

For more information about creating custom themes, see our Developer Documentation.
For more information about creating custom order form templates, see Custom Order Form Templates and Create a New Order Form Template.

As you make changes, make certain to use Git to add and commit them to your copy of the repository.

For more information on committing changes in Git, see Committing changes to your project and git-commit.

5. Upload the custom theme or template.

Upload your custom theme or template to the appropriate location for your WHMCS installation and configure WHMCS’s theme or template settings to use it.

We recommend testing customizations before updating and applying them to your production WHMCS installation. For more information, see Set Up a Test Environment.

Last modified: August 21, 2024