DOCS
clock Last Modified: Oct 4, 2018

Git development with Fork on macOS

Last modified: October 4, 2018

This is a step-by-step tutorial on how to manage your site’s source code by using Fork on macOS. Fork is a fast and simple git client for Mac and Windows, and Presslabs friendly, too.

In this tutorial, we will show you how to easily set up and make changes to your site’s source code using Fork, a fast, friendly, and open-source git client for Mac and Windows, which you can download here.

After installing the app, you will be asked to configure the User Name and the email that will be associated with your commits, as well as the Default source folder, which is the default folder where the repositories you clone will be stored.

The Fork Interface
info The Fork Interface

Clone your repository

Each site hosted by Presslabs has a git repository associated with it, containing your site’s source code, along with all the changes that have been made along the way. For more details, check our git specifications.

Additionally, we offer free development sites for development, so you should have at least one development site. This can be set up in two ways, so please check out our Development guidelines for insights regarding your development life cycle, depending on your development site setup.

To clone your repository locally, go to File -> Clone, which will open the following window:

Clone your repository locally
info Clone your repository locally

Here, you need to introduce your repository URL, which you can get both from our Dashboard and our Gitea interface, check our Access section.

We recommend cloning your repository using the HTTPS URL and your Presslabs Dashboard credentials. The alternative is to set up your SSH keys and clone your repository using the SSH URL.

Your HTTPS repository URL should be something like: https://git.presslabs.net/<site_owner>/<instance_name>.git.

The Name of your local repository should be the name of your instance, e.g mysite-dev. This is not a requirement, but it’s a good practice.

Press Clone, enter your Presslabs Dashboard credentials, and your repository will appear in the Fork interface:

Example of repository in the Fork interface
info Example of repository in the Fork interface

In Fork, you can have multiple repositories opened in different tabs, which allows you to quickly navigate to your repositories and organise your workflow efficiently.

How to commit and push changes

A commit records the changes to your repository (site’s source code) that were made to a file or directory. You can see in the Fork interface all the commits that have been made. The next steps show you how to make commits that have some changes in your source code and ultimately push them to your development site or production site.

Step 1: Create a development branch

The commits are stored on a branch, in this case in the default master branch. A branch is essentially an independent line of development. Creating a new branch allows you to work on new features or bug fixes in an isolated environment.

You can easily create a new branch by right-clicking the Branches section -> Create e new branch, which will automatically take you to that new created branch. You can easily switch branches by double-clicking them.

I have created a development branch named development:

Switching to the development branch
info Switching to the development branch

Step 2: Make commits with your changes on the development branch

Let’s say you want to add a robots.txt file, which is of great importance for search engines such as Google to index the web content of your site.

First, open your repository in your favourite text editor (e.g. Atom) and add the robots.txt file in the /wp-content/root/ directory:

Adding a new robots.txt file
info Adding a new robots.txt file

Now if you go back to the Fork interface, on the Changes section, you will see the newly added file.

The changes made to the code displayed in Fork
info The changes made to the code displayed in Fork

Fork shows you all the files you have modified and not committed yet. The green lines show the lines you have added, whereas the red lines show you which lines you have removed. Now you have to stage these changes, by pushing the Stage button. This adds your modified files to the queue to be committed later.

The next step is to commit these changes.

Making a commit with the selected changes
info Making a commit with the selected changes

When committing your changes, you are required to enter a commit message. The commit message provides comments regarding the changes you have made, so they should be as descriptive and easy to understand as possible. Press the Commit button and your changes will appear in the All commits category.

Let’s make some more changes. Let’s add some image thumbnails in the functions.php file of our theme, then stage and commit them.

Adding new image thumbnails in functions.php
info Adding new image thumbnails in functions.php
The new image thumbnails added seen in Fork
info The new image thumbnails added seen in Fork

Now let’s say you want to modify an image thumbnail, I’ll replace the large thumbnail with a small one. The modified lines are intuitively displayed in the Fork interface.

The Fork interface intuitively displaying changes
info The Fork interface intuitively displaying changes

You can visualise all these changes in the All commits section:

Overview of the commits made on the development branch
info Overview of the commits made on the development branch

Step 3: Merge your development branch in the master branch

After you finish developing your new feature or bug fixing, you need to merge these changes in your master branch.

First, you need to go to your master branch and make sure you have all the modifications from the remote repository. To to this, press the Pull button, which applies the latest changes from a remote repository onto your local repository:

Git Pull - get all the modifications from the remote repository
info Git Pull - get all the modifications from the remote repository

Then right-click the development branch and choose the Merge option.

Merging the development branch into the master one
info Merging the development branch into the master one

If there are no conflicts, your branch will be merged, and now your Master branch incorporates the changes too.

Overview of the now merged development branch
info Overview of the now merged development branch

Step 4: Push your changes to the remote repository (origin/master branch)

A push updates remote references along with associated objects.

The origin/master branch is the remote repository and it still points to the code from the server. So, the last step would be to push the changes to your remote repository (development site or production one).

First, make sure you are on the Master branch. To push the changes you can either use the Push button, or right-click on the master branch and choose the Push option.

Push the changes on the remote repository
info Push the changes on the remote repository

After pushing the changes to the remote repository, you can view them in our Gitea interface at git.presslabs.net or in your wp-admin in the Gitum plugin.

Revert a commit

How to revert a commit
info How to revert a commit

You can revert a commit by right-clicking in the Fork interface and choosing the Revert option. This will create a new commit that will undo the changes from the commit you want to revert.

The reverted commit
info The reverted commit

When working locally, the Fork interface also provides advanced options of rewriting the history of git commits like interactive rebasing and the reset option. But the Golden Rule of git is to not make such operations on the code that is public, so you may only perform such operations on your local code, before pushing it to the remote repository, for a more readable git history.

If you do however try these operations on production, our Gitium plugin will simply push back the commits that you try to «vanish», so the only way to undo a commit that is on production is to revert it.

How to handle conflicts when merging the development branch

While merging your development branch into the master one, the first step is to make a Git Pull, which applies the latest changes from your remote repository (development one or production) to your local repository. This means that while you were developing locally, someone else might have made changes that you have also made.

Let’s take an example. Let’s say you want to add a sitemap to your robots.txt file.

Adding a sitemap the robots.txt file
info Adding a sitemap the robots.txt file

You stage and commit your changes, and then you want to merge your developer branch into the master one as shown above.

You need to go on the master branch, Pull your changes, and now your git history looks like this:

The git history after pulling the changes from the remote repository
info The git history after pulling the changes from the remote repository

On your developer branch you have added a sitemap, reverted the commit, then added the correct sitemap. But someone also added a sitemap on the remote repository, which is now on your local master branch.

When trying to merge, you get a message saying that «The merge will require manual conflicts resolution». Now you can Cancel the Merge, or continue it and fix the conflicts.

Conflict appearing when trying to merge the development branch
info Conflict appearing when trying to merge the development branch

If you choose to continue the merge, go to the Changes section, to see what are the conflicts you need to solve.

The merge conflicts in the Fork interface
info The merge conflicts in the Fork interface

In Fork you can resolve your merge-conflicts easily using the merge-conflict helper and built-in merge-conflict resolver. Pressing the Merge in Fork button will open a new window showing you exactly the conflicted files. You can select what changes you want to keep and press the Resolve button and the Fork merge-conflict resolver will take care of the rest.

Details about the conflicted files
info Details about the conflicted files

However, sometimes it is not all black and white and you do not want to keep only your changes or the ones that were made on the remote repository, but to combine them. In this case, instead of selecting one change or the other, go to your conflicted file in your text editor, in this case it’s the robots.txt file:

The conflicts as they appear in the Atom editor
info The conflicts as they appear in the Atom editor

Here you will see that the conflicted lines are marked down like this:

User-Agent: *
Allow: /wp-content/uploads/
Disallow: /wp-content/plugins
Disallow: /readme.html
<<<<<<< HEAD
Sitemap: https://www.mysite.com/sitemap.xml
=======
Sitemap: https://www.mySiteIsAwesome.com/sitemap.xml
>>>>>>> development

The lines between the <<<<<<< HEAD section and the separating ======= are the code from the master branch, and the ones below are from your development branch. You can now combine the code as you see fit and make sure to remove the conflict separators:

User-Agent: *
Allow: /wp-content/uploads/
Disallow: /wp-content/plugins
Disallow: /readme.html
Sitemap: https://www.mySiteIsAwesome.com/sitemap.xml

Now, you need to commit the changes you have chosen, and the merge will be successful.

Commit the resolved conflict
info Commit the resolved conflict
The git history after successfully merging the development branch
info The git history after successfully merging the development branch