Git and Craft CMS: A great combination
Git is awesome. Craft CMS is awesome – let’s get them together!
I setup my Github repo to work on Panthur hosting servers (anyone in Australia who wants a new/better host you should really check them out, best Australian host I’ve used by a mile), but it should work similarly on any Linux based hosting which allows SSH access.
This guide assumes you have git installed on your development machine and have already setup your local repo. If you need a .gitignore file for Craft CMS you can get a default one here, I'd suggest adding the craft/app folder to the .gitignore too, it'll save you time pushing updates and also ensures the core system files are independent in each environment. If you've already made commits to your local repo then after you update your .gitignore you’ll need to make sure the repo knows about the changes by following the steps outlined here.
It's very important to remember that any files or folders in the .gitignore file will not be pushed to your hosting server - you will need to upload them manually using FTP. Make sure you remember this otherwise you could find yourself quite confused and frustrated.
Steps 1a and 1b are kind of Craft CMS / Vagrant specific, the rest is generally applicable to creating a remote git repo for any type of project.
Step 1a: Ensure correct file structure and config
The first thing you need to do is move the contents of the Craft CMS /public folder into the root of your repo directory. This is so the index.php, .htaccess and any other files in the /public folder are in the site root on your hosting server. After you move the files you’ll need to update the index.php to point to the new location of the /craft folder, just make the following change in the index.php file:
// Path to your craft/ folder $craftPath = './craft';
If you’re using multi-environment configuration and have set your ‘basePath’ and ‘baseUrl’ variables you’ll need to update /craft/config/general.php to match your new folder structure, this will just involve removing ‘public/’ from the end of your ‘basePath’ location.
Step 1b: Adjust Vagrant and Laravel Homestead config (if needed)
I use Vagrant and Laravel Homestead for my development environment so I need to make some additional changes to make sure the local site still works.
Open your Homestead.yaml file and change the ‘folders’ setting for the relevant folder so the ‘map’ and ‘to’ values don’t have the ‘/public’ folder on the end.
After this you’ll need to reprovision your VM, enter:
vagrant provision
Step 2: Initialize a bare repo on your hosting server
If you’re with Panthur you can just get an SSH permit that allows you console access for however long you need it, which is great. No matter which host you’re with though, if you’re going to use git you’ll need console access - so make sure your host has it. Panthur comes with git pre-installed, you may need to install it on your host first (how to install depends on your host’s Linux distribution, this link should get you started).
To initialize a bare repo on your host, just SSH in (using something like Putty if you're on Windows) and create a new folder to store your repos (this doesn’t need to be a publicly accessible folder). Then cd into that directory
mkdir repos && cd repos
Now initialize a bare repo inside this directory by entering the following (replace ‘example.git’ with whatever you want to call the folder which contains your repo).
git init --bare example.git
Step 3: Setup post-receive hook to move files to your server root (ie. make your website work)
After the repo is pushed to your hosting server you want to make sure the files are placed in the publicly accessible root folder, so as to make the website work and all. To do this we need to setup a post-receive hook.
From within your repository folder (example.git created above) enter the following command:
nano hooks/post-receive
This opens the nano editor and allows you to enter text into the post-receive file. Enter the following text into the file and then press Ctrl+X to exit (you will be prompted to save, just press ‘Y’ and to name the file, just press enter to leave the filename as its default). Be aware that the value of ‘GIT_WORK_TREE’ should be the path to the public folder on your server, the value below is just an example, you’ll need to determine your own correct value.
#!/bin/sh GIT_WORK_TREE=/home/example-name/public_html git checkout -f
After the post-receive file has been saved, you need to edit is permissions to ensure it is executable:
chmod +x hooks/post-receive
Step 4: Add a new remote to your local repo
Back on your local PC you need to add the bare repo you just made on your hosting server as a new ‘remote’ for your local repo, this allows your local repo to push updates to your hosting server.
Open your terminal, or console, or Git Bash cd into the directory which contains your local repo and enter the following command:
git remote add remote-name ssh://username@server.example.org/home/example-name/repos/example.git
You need SSH access to your hosting server for this to work, username is your SSH username, remote-name is the alias you want to give this remote (it could be anything but you should try to make it relevant) the rest is the absolute path to your git repository folder as defined earlier.
Windows does not come pre-installed with git, however if you install Git for Windows you should get Git Bash installed with it which provides local command line access to git.
Step 5: Commit any changes to your repo
I add and commit files using the command line - usually what I do for the initial push is add all the files from the repo, create a commit, then push to the server:
git add -A git commit -m"First commit for push to live hosting server" git push remote-name repo-branch
For the push command above replace 'remote-name' with whatever you called your remote and 'repo-branch' with the branch you want to push, most likely it will be master.
Now your local git repo will be on your hosting server and any changes you make locally can be pushed to your server simply by typing the git push command above.
Final notes
Remember you’ll also need to import your database to your hosting server and have the database settings configured to work with the database on your hosting server. You should really setup multi-environment configuration to make this process as seamless as possible – this link provides all the info you should need to set up multi-environment config for Craft CMS.
