Raghu Srinivasan

The goal of this write-up is to introduce you to the absolute basics of the distributed version control system called Git. Rather than jump right into a lot of syntax and commands we will use an analogy of a piece of text that we want to change and see how Git helps us manage to make these changes. In this article we are going to start with an extremely simple flow just to get a feel for the basic concepts and yes, just a handful of commands. We'll also see how easy it is to 'go back in time' to a previous version of the story if we want to.

Let's say we have a paragraph of text that was written for a British audience. Below is the current version of the story. Note the version is v1 and there is this random-looking alphanumeric string: 7f3c9ab This random-looking alphanumeric string is called a hash and is a unique identifier for this version of the story/code. You can think of it as a fingerprint for that version of the story/code. Each time we make a change, a new hash is generated - as we will see below.

The task: these names, spellings and vocabulary work in Britain. Make the language more American friendly.

Say you are the ‘editor’ and you decide to divide up the task among three people: the first is an expert on names, the second on spelling variations and the third on vocabulary differences.

Person1, Person2, Person 3 all need a copy of the original paragraph. To do this they make a copy or clone of the original text. In terms of code this "original text" is stored in a repository. And, in fact the command is called git clone. Once they do this, they each get an identical version of the original. Now, so as not to mess with the original, they make a secondary copy of the repository/story to work in. This secondary copy is called a branch in git.

To make this second copy they use this command where the -b means a new branch git checkout -b <branchname> so the first person might issue a git checkout -b fix-names and the second might do a git checkout -b fix-spellings and the third might do a git checkout -b fix-vocab. The names of the branch could be anything of course, but it is a best practice to name the branch in a way that is descriptive of what change one intends to make.

Each person changes only the sentence they are responsible for.

Person 1 thinks the names Joe and Bob sound more typically American and makes the change.

Person 2 then looks at sentence 2 of their fix-spellings branch and then makes the change to “Their favorite colors were Red and Blue respectively” in the second sentence.

Person 3 then looks at sentence 3 of their fix-vocab branch and then makes the change to “They picked up their car after they got its hood fixed and drove it home after getting some gas. They shared an apartment on the 5th floor which they took an elevator to get to”.

Once each of them has made the change, the first thing they do is commit, or make permanent, their changes locally. They do this by typing these commands: git add . followed by git commit -m "an explanation of their changes". The "add ." is shorthand for add everything, in this case just the one file they changed. The commit -m commits, or makes permanent locally, their change with the message specified by the text after the "-m". All this is still local to each of their local machines. For you, the editor, to see their changes and review them, they need to send their changes to the remote repository that you have givem them access to when they did the initial git clone. They do this by using the command git push -u origin <branchname> where origin is like an alias to your original repository.

Each of them now sends you the changes in their branch to review. They do this by opening what is called a pull request or PR i.e. they are requesting you to pull their changes into the ‘main’ version. Assuming you approve of their changes, of course!

At this point you have to review their changes. In other words you are about to embark on a code review. Remember, each PR contains all three sentences (because, remember, they cloned the repository) but each person has changed just the sentence they are responsible for i.e. each branch is now a snapshot of the original with just their one surgical change.

In a code review, you are mostly checking to see if you agree with their changes. Let's say that when reviewing the first PR you decide that Joe and Bob are too generic and send it back with comments asking for more typically American names.

For the second PR, your only concern was the extra u in colour and favourite and you’re happy with their changes. You can now accept their change and this is called a merge where you combine their change/branch with your mainand now the main branch becomes what is shown below. Note the version has changed from v1 to v2 and the hash has also changed from 7f3c9ab to c91e4d2.

Finally, you review the third person’s PR and you are also happy with that as it is. You are ready to accept their change.

Remember though that because the version submitted by the 3rd person still has the ‘u’s in favorite and color while you have already merged the one without the ‘u’s you have a mismatch. What happens now? Will Git overwrite your latest version with this third person’s version, resulting in your losing the second person’s changes?

Luckily for you, in this case, because they changed different parts of your story/code, Git can do an Auto-Merge i.e. it can resolve the merge by itself without you having to do anything. It can stitch them together cleanly by keeping your commits sentences #1 and #2 but overwrite just sentence #3. At this point the main repo looks like:

Then the first person comes back after taking your feedback (“code review”) with “There were once two friends Taylor and Jackson” and submits another PR to you.

At this point you are happy with those names and are all set to merge when you hit the same conflict but then again because the changes are on different parts of the story (or code) Git will again resolve the conflict for you by doing an Auto-Merge and stitch them together by over writing just the first sentence and keeping the other two to get this final version:

• git clone gives multiple people the same starting point.
• git checkout -b <branchname> lets each person work separately.
• A Pull Request is a request to pull those changes into main.
• Code review happens before the merge.
• If people changed different parts of the story/code, Git can often Auto-Merge.