The code of all the sites hosted with Presslabs is stored on our Git servers stack. Each site has its corresponding Git repository, where the history of your code resides. So, in order to manage your site’s source code, you need some basic Git knowledge.
Git is an open-source version control system that helps people work together simultaneously, using the same files and the same code.
You can install Git on all operating systems. Check their official installation guide here. For Windows, we recommend you to install Git for Windows, which provides a BASH emulation used to run Git from the command line.
If you want to use a Git Client instead of using git from the command line, we’ve put together some tutorials for GitHub Desktop and Fork, both Windows and macOS.
For a proper development life cycle, make sure to also check our Presslabs development guidlines.
A repository (usually abbreviated “repo”) is a location where all the files for a particular project are stored, in our case, your site’s source code. Each site hosted by Presslabs has its own repository, and you can access it with a unique URL. At Presslabs, we offer free development sites, each having its own corresponding repository.
We highly recommend you to make changes to the production site only after thoroughly testing them on your development site. For this reason, the examples below will use the instance mysite-dev to encourage you to test your changes on the dev site first. Don’t forget to replace mysite-dev with the actual name of your development instance, or with the name of the production site.
To clone a repository means to create a local copy of the code, so you can develop a new feature or make fixes to the current code. The local copy of the code will be reffered to as the local repository and your site’s source code (the production one or the development one) will be reffered to as the remote repository.
There are three areas where file changes can reside from Git’s point of view: working directory, staging area and the repository. When you make changes to your project, you’re dealing with your project’s working directory. All the changes you make will remain in the working directory until you add them to the staging area (via the git add command). The next step is to commit the files that you’ve staged in your local repository. The commit operation enables you to record changes that were made to a file or directory in the Git history. This way, you’ll be able to view all the changes you’ve made to your site’s source code, chronologically.
Pushing the changes from your local repository to your remote repository (production site or development site) will determine the update & sync of the remote repository with the local repository. You can see all the commits made to your remote repository in Gitea, in the Commits section of each repository.
A branch is an independent line of development, that allows developers to share and work on the same source code. This way, each developer can branch out from the original code base (create a new branch) in order to work on a new feature or fix bugs without affecting the work of their fellow developers.
When making the first commit in a repository, Git will create a master branch by default. All the commits you make will go under the master branch until you decide to create and switch to another branch.
Merging a branch into another branch means integrating the changes from the first branch into the second one. Usually, you want to merge a branch into the master branch after you finished developing or fixing something.
Clone your repository
Open the terminal and navigate to the location where you want to clone your code, for example:
In case you are a total beginner in working with command lines, here is a great tutorial that explains the two basic navigation commands: ls and cd.
You can clone your repository using two protocols: the SSH protocol or the HTTPS one. To clone a repository using the SSH protocol you need to set up your SSH keys. However, when cloning a repository using HTTPS, you will have to provide the same authentication credentials you use for the Presslabs Dashboard.
Clone your repository using SSH:
git clone email@example.com:user/mysite-dev.git
Clone your repository using HTTPS. You will be asked to authenticate using your Presslabs dashboard credentials.
git clone https://git.presslabs.net/user/mysite-dev
Cloning into 'mysite-dev'... remote: Counting objects: 8106, done. remote: Compressing objects: 100% (122/122), done. remote: Total 8106 (delta 89), reused 60 (delta 31), pack-reused 7951 Receiving objects: 100% (8106/8106), 24.37 MiB | 1.22 MiB/s, done. Resolving deltas: 100% (4225/4225), done.
Go to the repository directory. You can run a ls command to visualize your repository’s content or open the repository in the file manager of your operating system:
total 32 -rw-r--r-- 1 ioana ioana 428 aug 20 16:08 index.php -rw-r--r-- 1 ioana ioana 17 aug 20 16:08 info.php drwxr-xr-x 3 ioana ioana 4096 aug 20 16:08 provision -rw-r--r-- 1 ioana ioana 636 aug 20 16:08 README.md -rw-r--r-- 1 ioana ioana 808 aug 20 16:08 Vagrantfile drwxr-xr-x 2 ioana ioana 4096 aug 20 16:08 wordpress -rw-r--r-- 1 ioana ioana 3048 aug 20 16:08 wp-config-vagrant.php drwxr-xr-x 7 ioana ioana 4096 aug 20 16:08 wp-content
Check out your git status:
On branch master Your branch is up to date with 'origin/master'. nothing to commit, working tree clean
Here you can find all the code changes that differ from the version stored in the remote repository. If you didn’t have any changes, a message will appear to inform you that your branch is up to date with ‘origin/master’, which is the master branch of your remote repository. It will also tell you that there is nothing to commit, since you have no commits made yet, and your working tree is clean, since there are no staged changes.
Create a New Branch for Development
You can make changes on the master branch and then push them directly to the remote repository (your development site or the production one). However, it’s a good practice to create a new branch for each task, like bug fixing or developing new features, and after finishing your work to merge the branch into the master branch and only then push your changes on the remote repository.
Create a new development branch:
$ git branch development
List the existing branches to check your newly created one:
development * master
Switch to the development branch so you can start working on your new feature or fixes:
git checkout development
Switched to branch development
Making Changes and Committing Them
Any change you make on your repository’s files and directories will be recorded. To see them, use the git status command mentioned before.
Let’s say you want to add a robots.txt file, which holds great importance for search engines such as Google that index your site’s web content. On our platform, the robots.txt file should be placed in the /wp-content/root/ directory.
I will open the project in Atom to add the robots.txt file. Atom intuitively displays the new files you’ve added or modified and have not been committed yet. It also shows you the branch you are working on, in this case development. Atom comes with built-in basic Git and GitHub integration, which means you can also make commits directly from the Atom interface, but this is not the point of this tutorial.
You can run a git status command to show you the modified files:
On branch development Untracked files: (use "git add <file>..." to include in what will be committed) wp-content/root/robots.txt nothing added to commit but untracked files present (use "git add" to track)
Git tells you that you have an untracked file, which means you have added a new file, at
wp-content/root/robots.txt. It also suggests you what to do next: to use the git add command to stage the changes for the next commit.
git add wp-content/root/robots.txt
If you have lots of changed files and you want to include all of them in the next commit, here are some useful commands:
git add -A //stages all the changes git add . //stages the new and modified files, without the deleted ones git add -u //stages modified and deleted files, without the new ones
To undo a file you added but hasn’t yet been committed, you can run a reset command, followed by the name of the file in question:
git reset wp-content/root/robots.txt
After you’ve finished staging the changes, the next step is to wrap them up into a commit:
git commit -m "Added the robots.txt file"
To visualize the history of the commits, you can run a git log command. This will show you all the commits you’ve performed, together with a commit message for each of them, so they can be easily identified — this is the reason why the commit message is so important.
commit 072f7d92de54852e8212279420dae80a35e96015 (HEAD -> development, origin/master, origin/HEAD, master) Author: user <firstname.lastname@example.org> Date: Mon Aug 20 16:18:18 2018 +0300 Added the robots.txt file commit 3cce2c7ff81a5f8d6c6a7b0b5c1c7c1f2ad77282 Author: user <email@example.com> Date: Mon Aug 20 15:54:20 2018 +0300 Added a new feature commit 88c6e01e696cec8e6cbb9c0f75f20c62c05adb74 Author: user <firstname.lastname@example.org> Date: Fri Aug 17 13:49:23 2018 +0300 Revert "Improved the theme" This reverts commit 3395683f3e320eda9e5ec57f7c81224ced6922af. commit 3395683f3e320eda9e5ec57f7c81224ced6922af Author: Ioana <email@example.com> Date: Fri Aug 17 13:30:59 2018 +0300 Improved the theme
Each Git commit is identified by a unique SHA-1 hash, which you will need for certain Git operations.
Revert a Commit
To undo a commit, you can run a git revert command, followed by the SHA of the commit in question. This will generate a new commit that undoes all the changes made in the commit you want to revert.
git revert 6ffa13ce23238c2f7f7425e8e966bbff8091a1ca
This is the only operation to undo a commit on a production site.
There are also more complex operations to undo changes: git rebase and git revert, but such operations need to be handled carefully, since they rewrite the git history. The general rule is that you should not change history that you have published, because somebody might have based their work on it. For this reason, you can use these commands on your local repository, but we do not allow them to be used on commits that are already pushed on the remote repository (production or development).
Merging the Development Branch
After you’ve finished developing, you need to incorporate the changes from the development branch into the master branch.
Go to the master branch:
git checkout master
Switched to branch 'master' Your branch is up to date with 'origin/master'.
While you were developing locally, someone else may have made changes on the remote repository, so you need to bring the changes to your local repository, as well. To do this, run a git pull command:
Username for 'https://git.presslabs.net': mysite-dev Password for 'https://firstname.lastname@example.org': Already up to date.
In case you have cloned your site with the HTTPS URL, you will be asked to enter your credentials, either when you pull the changes from the remote repository, or when you push them. If there are no changes made on the remote repository, you will be notified that you’re «Already up to date».
Merge the development branch into the master branch:
git merge development
Merge made by the 'recursive' strategy. wp-content/root/robots.txt | 5 +++++ 1 file changed, 5 insertions(+)
Be aware that in case someone else has made changes to the same files as you have, there will appear some merge conflicts you need to fix.
Also, Git will open a text editor to introduce a commit message for the merge operation. In case it opens Vim, which is an editor directly from a command line, you need to type
:q to exit it without editing the default commit message.
Conflicts when Merging the Development Branch
In case someone else has modified the same files as you have, Git does not know which changes to keep. So you need to manually choose the changes you want. Conflicts may appear, for instance, when you pull your changes locally or when you try to merge one branch into another.
Let’s say someone else has added a robots.txt file on the remote repository:
User-Agent: * Allow: /wp-content/uploads/ Disallow: /wp-content/plugins/ Disallow: /readme.html Sitemap: https://www.mySiteIsAwesome.com/sitemap.xml
In this case, the sitemap you added locally is different from the one on the remote repository.
git checkout master git merge development
Auto-merging wp-content/root/robots/text CONFLICT (add/add): Merge conflict in wp-content/root/robots.text Automatic merge failed; fix conflicts and then commit the result.
When trying to merge the development branch, git will intuitively let you know that the merge failed and you need to fix the conflicts and commit the result.
To solve the conflicts, open your text editor, which will intuitively display which lines are in conflict. The lines between the
<<<<<<< HEAD section and the separating
======= represent the code from the master branch, and the ones below are from your development branch.
Atom offers you the possibility to choose what changes to keep, with a simple click. Since we are trying to merge the development branch into the master one, Atom calls the changes from the master branch our changes and the ones from the development branch their changes.
If you run a git status, Git will direct you to fix the conflicts and run a git commit.
On branch master Your branch is up to date with 'origin/master'. You have unmerged paths. (fix conflicts and run "git commit") (use "git merge --abort" to abort the merge) Unmerged paths: (use "git add <file>..." to mark resolution) both added: wp-content/root/robots.text no changes added to commit (use "git add" and/or "git commit -a")
Since we fixed the conflicts, simply add and commit the result and the merge will succeed. You also have the possibility to abort the merge by running the command git merge –abort.
git add wp-content/root/robots.txt git commit -m "Fixed merge conflicts"
Pushing the Changes to the Remote Repository
You commits are on your local repository. To push them to your remote repository as well (production or development site) so you can visualize how they affect your site, run a git push command:
Username for 'https://git.presslabs.net': user Password for 'https://email@example.com': Enumerating objects: 8, done. Counting objects: 100% (8/8), done. Delta compression using up to 4 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (5/5), 534 bytes | 534.00 KiB/s, done. Total 5 (delta 2), reused 4 (delta 2) To https://git.presslabs.net/user/mysite-dev.git 3cce2c7..072f7d9 master -> master
You can visualize the changes on Gitea, in the Commits section of your repository.
I have made a commit and put my site down. What do I do next?
Don’t panic, you can fix it in just a couple of minutes.
Please remember that you see the site as being down because you are logged in, but for the rest of the users the site is up and running, as it’s served from cache.
When you try to access the site, you’ll receive a warning message like this one:
Copy the error reference you see in this warning message and go to the Logs section of the Presslabs Dashboard to find out more about the reason your site crashed. You can search in the logs for the error reference you’ve just copied.
In this case, it’s a syntax error, so you can simply go to that file in Gitea, click on the edit button, fix the syntax error, and save the changes.
However, sometimes the commits are more complex, and you do not want your site to be down until you manage to solve the problems. So you need to Revert the commit that put your site down, so that your site is operational again. After that, you can create a development branch and properly work on the bug fixes.
To revert a commit, copy your instance locally. You can get the clone URL from Gitea:
git clone https://git.presslabs.net/user/mysite-dev.git cd mysite-dev
If you clone your site via HTTPS, you will need to introduce your Presslabs dashboard credentials. If you use the SSH URL, you need to have your SSH keys set up.
Run a git log command to check all the commits that were made.
commit 072f7d92de54852e8212279420dae80a35e96015 (HEAD -> development, origin/master, origin/HEAD, master) Author: user <firstname.lastname@example.org> Date: Mon Aug 20 16:18:18 2018 +0300 Improved the theme commit 3cce2c7ff81a5f8d6c6a7b0b5c1c7c1f2ad77282 Author: user <email@example.com> Date: Mon Aug 20 15:54:20 2018 +0300 Added a new feature commit 3395683f3e320eda9e5ec57f7c81224ced6922af Author: user <firstname.lastname@example.org> Date: Fri Aug 17 13:30:59 2018 +0300 Added the robots.txt file
Get the SHA of the last commit made, in this case the
Improved the theme one, and run a git revert command, followed by the SHA you have just copied. This will create a new commit that undoes the changes from the commit specified.
git revert 072f7d92de54852e8212279420dae80a35e96015
Git will open a text editor to modify the revert commit message. You can also leave the default one. In case it opens Vim, which is an editor directly from a command line, you need to type
:q to exit it without editing the default commit message.
Run a git push with the newly created revert commit and your site will be up and running in no time.
How can I revert multiple commits?
Since the only operation possible to undo changes on a production site is to revert the commits, it can prove quite troublesome to manually revert a large number of commits.
You can revert multiple commits by specifying the range of commits you want to get reverted.
git revert master~3..master
This command will revert the last 3 commits from the master branch.
How can I install a theme/ plugin with Git?
Firstly, you need to have the archive of the plugin/ theme. You can download it from wordpress.org or from the site of the theme/ plugin.
Clone your site locally:
git clone https://git.presslabs.net/user/mysite-dev.git cd mysite-dev
Unzip the plugin/theme and copy the folder into wp-content/plugins or wp-content/themes.
Now make a commit with the newly added plugin/theme:
git add . git commit -m "Added a new theme/plugin"
Push the changes to the remote repository:
Now you need to go to your wp-admin and activate the theme/ plugin.