Use Git to Work Together

8 min readOct 3, 2021

Imagine you are working in a team to write a book and some of your team members are working on chapter 1 while others are assigned to work on chapter 2. After each writer completes their assigned chapter, the works can now be merged into one complete book.

This method however has a risk. While in a small group, each may split into different topics or sections (i.e. new document) when working together but unavoidably, one might accidentally step on another person’s section (or file) during editing. The resulting conflicting work may become hard to resolve as it will be difficult to trace the version history across multiple writers or editors.

Thus, using git can be the solution to resolve this problem easily.

Why use Git

Git is a versioning tool that keeps all revisions of your document so that you wouldn’t lose any changes made since “day one”. You can easily compare the difference between revisions in text form. Based on this design, it is easy to fully rollback if something went wrong in your latest work.

Git offers a unique feature called branching. Branching can help the team to work on different topics and scope while not stepping on other’s work to reduce conflict. After work is done in a “branch”, it can be merged back into the main pipeline without worries of losing any of the work done. Usually, a check and review is done before the merge is done where any potential conflict of work can be resolved without jeopardizing the original source or others’ work.

In this article, I’ll try to introduce some simple git commands that can be utilized in the use case above for non-programming backgrounds. The reason the team is using Markdown (or pure text) format but not using Microsoft Word for writing the book is because Microsoft Word file format is in an encrypted format which has no meaning when doing revision control on it as it would fail to do the diff (comparison to previous revision).

But sure, you can argue that Microsoft Word do have some form of revision control. However, the inconveniences will reveal itself when working together on a same file in a group. The effort to manually fix all the possible conflicts by eye poses a lot of of unnecessary work, not to mention that mistakes are prone to happen. Thus, a better tool such as git would surely be more desirable.

Lets discuss more about how to setup Git. But

Prerequisite

Before starting, install git from here.

For text editors, you can install Visual Studio Code as it is built-in with git making it easier for executing the git commands from frontend. By default Visual Studio Code had implemented supports for Markdown syntax and preview.

Getting Started

It is recommended to use any free online git provider to get your project started. Of course, the files can always be hosted locally without any git providers. But for beginners, platform such as GitHub, Bitbucket, GitLab is a good start. After the project setup, team members can then be invited to work together in the project.

To create a project and start working get its link for downloading:

Go to register an account in GitLab. It is free!
Create a new private project > Create blank project. You also can create a public project if you don’t mind sharing your files to the world.
Go to your project just created > Clone > copy the URL in ‘Clone with HTTPS’.

Next, is time to download the project into our local (If you do not prefer the command prompt, you can disregard the section below and directly refer to Visual Studio code section.).

Download from Server

Launch git bash locally and set the targeted folder for download as desired.

To initiate the download, we will use the git clone command:

git clone https://gitlab.com/yourname/yourproject.git

For first time users, the setup configuration need to be done that requires the user name and email to be able to execute any git commands. This is only a one time configuration.

git config -global user.name “John Lee”
git config -global user.email john.lee@gmail.com

After the clone process finished, your computer should contain a new folder with the same project name as created in GitLab. It contains all the files of the project on the server (or empty if you just started).

Editing

After the download process is complete, it is time to start editing the files locally. These works and changes are done locally and does not overwrite the copy found in the git server itself. To update the master copy in the git server, execute these commands:

git add .
git commit -am “Describe what you have done in your changes 1”

Add command tells git bash to add all new files. This command is only required when there are newly created files. If not, git commit is the only command that is needed. Think of Git commit like brick layering. A builder place one brick at a time that slowly form a wall. A commit is like a “brick”, a block of work that is ready to be sync to the master copy. Take note that a commit will not update the master copy in git until a push is done.

To describe the block of work done by each commit, the parameter -am can be used. It tag the commit with a customized message that can be used to describe the work.

This cycle is repeated continuously until the work is done. Prefer to commit small chunks of works frequently? Or commit big chunks of work periodically? Its all up to you!

Push and Pull

After several commits, you may be ready to push your work to update the master copy in git server.

git push

When done so, other team members will be able to download your portion of the update or work done. In doing so, git will also check the various commits for conflicts in cases where the master copy in git is updated by someone else.

To get download updates or other team members work to your local, we use the pull command. Everyday before you start your work or you want to get the latest changes by your team members,

git pull

will get the latest from the master copy in the git server. It is recommended to pull the changes as frequently as possible to reduce the conflict happening at your local. This is because files may be corrupted or overwritten if others work on the same file as you and pushed to the server earlier than you.

Which is why a good practice is to make sure you don’t have pending changes when calling the git pull command.

Visual Studio Code

As an alternative to using git bash to perform the clone, push and pull, Visual Studio Code can be used to perform the same actions without needing to type the commands. Visual Studio Code is a programming editor that can be used as a text editor. There are more than a thousand extensions you can get for free to improve productivity in Visual Studio Code.

If you find it too difficult to use git bash and all the commands, you can directly use Visual Studio Code as your choice. To clone a repository:

Start Visual Studio Code > Clone Git Repository > Paste your git repo URL.
You may start work on your file as normal now.

To commit your changes:.

Click on git button on left panel
Select the file and stage. At this step, you can see the latest changes compared with the last revision by clicking on the file. If you think that is not what you want, you can even discard all the changes completely by press on the ↶ icon.
Enter message > Commit.
Lastly go to more (three dots) > Push.

A single push can contain multiple commits. Not necessarily to push after every commit.

Similarly, when you switch from using git bash to Visual Studio Code, you will also need to get the latest update (pull) frequently to avoid conflict at your local copy.

For more details of using git in Visual Studio Code see https://code.visualstudio.com/docs/editor/versioncontrol

Branch

Things can get complicated when the more people are involved in a project and the file structure gets larger. For example a folder structure like below.

Team members can assign some work in a certain folder (chapter) to a branch. A branch is a “split-off” version from the master copy. When the scope of changes and works are too big and risky to be done in the master copy, branching gives the feature to work safely in a contained environment. It allows editing without the risk of constantly conflicting with others’ work.

To create a new branch:

git branch <name of branch>

After completion of the work, users can then merge the work back to the main code base ( master branch).

Lets take an example. Branch1 contains Chapter1 structure, while branch2 contains Chapter2 structure etc. After each (branch) has completed their part, they then merge back to master in order to have the complete chapters in the book with full structures and folders. By splitting the folder works based on branch, this can reduce the chances for team members to step on each other’s works.

Merge

Once the team has finished the work in a branch and more confident of the changes made, it is probably the right time to merge back the changes to the master branch so that the rest of the team can get the latest changes.

But first, it is good practice to raise a merge request (MR). The easiest method to do this is through the GitLab interface.

Go to your GitLab project.
Left panel > merge requests
New Merge Request > from your working branch and target set to master.
Merge.

The advantage of raising a MR is so that your team members can review your work, comment and approve before merging back into the master branch. To merge back, its as easy as clicking the merge button in GitLab MR ticket.

Alternatively, you can perform the merge command through git bash. The commands are:

git checkout master
git merge working-branch

This is a very crucial step because you might encounter conflict if the affected files has already been changed in the master branch (Someone may have committed changes in the same file that overlapped with yours). So you need to resolve all the conflicts locally and only can successfully merge your branch.

Once the changes are merged back to master successfully, other team members are required to pull from the master to get the latest changes.

Now that you have get acquainted with 5 main commands (commit, pull, push, branch, merge), why not give git a try for your team project?