Wednesday, 18 February 2015

How-to: Introduction To Git [Guest Post]


Command and Conquer: Introduction to Git by Lucas Westerman originally appeared in Full Circle Magazine Issue 84

I received an email from a reader of Command & Conquer, asking me to write an article on using Git – specifically things such as what a fork is, what pulling is, and what exactly a commit is. He also followed it up asking about auto-merge errors and how to fix them. I will do my best to cover each of these points in particular.

However, as most of my experiences with Git are via Github, which offers some extra functionality on their website that isn't the “vanilla” Git experience, there may be some aspects of my explanations that do not apply to a custom git server.


GENERAL INFORMATION

In Git, you can create a repository (which typically contains a master branch). However, a repository can contain multiple branches – such as stable, testing, and development. A repository can  be forked by anyone, and that will result in a local repository for the user who forked it.

A Branch
A branch could essentially be considered a snapshot of your project at a certain point. Some people advocate assigning every change to a branch, while some people keep only one or two active branches (while keeping the master branch as a basis for any future branches). Via example: If you are actively developing a web browser, you could keep two branches – stable and testing.
  • Stable contains the source code for your last official release – which is hopefully bug-free.
  • In order to keep development moving along, you would also have a branch called Testing, which contains all the bleeding edge code. You can track your changes, and get input from beta testers, in  order to work your way towards a new update to stable. Once you reach a point in testing that's stable and running as you'd like it, you would then update those  changes to stable, and keep working on testing.

A FORK
Is when a user sees a project they like (i.e. the web browser project from my last example), and think to themselves “I could do this better”, or “I'd love to help create this”. Instead of assigning users the ability to edit the official repository and its branches, the user would instead create a fork of the project.

You can imagine it as a highway (the official repository), with turn-offs for every user who is contributing to it, which leads to their local copies. This is useful, as it prevents the main goal of the original project from shifting – if  you want to re-purpose the code for a web browser to create an image gallery, you can fork it as normal, and make any changes you'd like.

Some of you may be wondering how these forks can help contribute anything to a project, if it's essentially a copy. This is handled by something called a merge (explained below).

A Commit
Before we discuss what a merge is, we should first explain commits. Whenever you change a file in your local repository, you can choose to save it as a commit (i.e. a change), give it a brief explanation, and then push (upload) it back to your remote repository, so that the updates can be propagated through all forks based off that repository, as well as give the most recent versions to any new forks.

A Merge
Once you've committed changes to your remote repository, and believe that it would help the original project, you can then send a merge request for that commit (or a series of commits). This then sends a notification to the owner of the original repository, and includes information on the commit, displays a comparison of the before/after, and indicates any conflicts (if, for example, you've already changed the line of code slightly, and the patch can therefore no longer “find” it). Say you write a patch for the web browser that allows users to define their own CSS (cascading style sheets), in order to style their browser and website views to their specifications. To do so, you adjusted a for-loop that runs over all files within folders called “config” and “data”, to include the folder “styles”. However, upstream (the original project), has changed the name of the config folder to “conf”. This means that the loop looks different than expected to the merge request – which raises a conflict with the original developer. They can then choose to resolve it, or ignore it.

RESOLVING CONFLICTS
If you run into conflicts with merges (i.e. two people edit the same file, or one person edits it and another deletes it), you will generally need to resolve it manually. To go about doing this, you would run git status This will give you information about what files are in conflict, as well as give you instructions to indicate when you have solved the conflict.

Viewing the actual conflict is as simple as opening the file after the merge has failed – the file should contain a block that looks something like:

the number of planets are
<<<<<<< HEAD
nine
=======
eight
>>>>>>> branch-a

The series of less than/greater than signs mark the area of the conflict, and the line of equals signs mark the two different changes. Branch-a refers to which branch this conflict is occurring in. To resolve this, simply delete the conflict markers (less than, greater than, and the equals signs), as well as deleting either your change, the other person's change, or replacing the entirety of the conflict with a new edit (i.e. something that contains both edits). Once the markers are gone, you can go about adding it to the commit list, and pushing it to the remote repository.

In the case of a conflict caused by someone deleting a file, you can resolve it in one of two ways:
  • Adding the file back, and then committing it (which essentially overrules the commit where it was deleted).
  • Deleting the file with git rm, and then committing the change again.

WHAT IS A PULL?
A pull is a combination of git-fetch and git-merge. Fetch essentially asks for any changes to the repository, and downloads the commits. Merge then tries to integrate the new information into your existing copy of the repository. Instead of having to do these things one by one, Git instead offers the pull command, which automatically attempts to merge anything downloaded via fetch.

WHAT, NO CODE?!
This month, I decided I would focus on explaining the terminology and illustrate some aspects of Git. Next month, I will run you through a series of examples for setting up a git repository, cloning it, editing the branches, creating a commit and resolving a conflict. For anyone who does not want to wait a month, there are links to information in the further reading section below. Hopefully this article has helped to shine some light on the terminology of Git.

Further Reading
http://git-scm.com/doc – Git Documentation
http://githowto.com/ - Git Howto website
https://help.github.com/ - Github offers some well-written explanations for the typical uses of Git, as well as explaining Github-specific features well.

Lucas has learned all he knows from repeatedly breaking his system, then having no other option but to discover how to fix it. You can email Lucas at: lswest34@gmail.com.


No comments:

Post a Comment

At least try to be nice, it won't kill you...