Git Introduction

on git, introduction

At this point you should have an index.html file sitting in a basic-html directory. If you don’t know what I’m talking about then be sure to run through the previous post. You also hopefully have git installed on your machine, and have a github.com account.

If you are unsure if git is installed, open a terminal window and run the command:

$>git --version
git version 2.2.2 #or whatever your version number is

So what is all this git business?

This is a topic that can (and has) filled many books. It is a very flexible program and can be used in a number of ways. I will atempt to give a very simplified rundown, and walk through some of its basic usage. Just enough to get you going and fufill basic development needs. As we progress with lessons we may begin to explore some of the more advanced git features.

First things first. There is often a lot of confusion about the relationship between GitHub and Git. They are not synonymous. Git is revision (or version) control software, something you install and use on a system. You can use git on your local machine without GitHub, or even without an internet connection. GitHub is a web service, that allows you to have remotely accessible git repositories. A git cloud *cringes* of sorts.

Why use GitHub at all? You certainly don’t have to, and there are other places that provide a simliar service. Bitbucket is a popular GitHub alternative, and you will often find git services on integrated development servers, like Pantheon or Heroku. I like GitHub, because it is very intuative and helpful. A lot of what is going on is represented graphically, complete with explinations. This will help tremendously as you learn. To answer the question more generally, we want to use a remote service like GitHub to be able to collaborate with other developers, and to serve as a backup or master copy of our code.

Right…​ so what IS git?

To really understand what git does you need to understand the principles of version control. This can get a little confusing very quickly, with all kinds of charts trying to explain what happens to a codebase as it goes through commit, branch, and merge operations. But at it’s heart, version control can be thought of as a working history.

Think about applications you use, say Google Chrome for instance. You have been happily using Chrome for a while and it works great. One day Chrome performs updates, and suddenly things break. Pages don’t load, videos don’t play. You can’t browse Reddit! OH NO! So you do some research in another browser and see that the current release of Chrome is buggy, and it is suggested you roll back to the old version. You see that you are on Chrome version 43, so you install the previous Chrome version 42, and all is well again. This (albeit poor) example is version control in action. There is a release history to Chrome, and when one version doesnt work you can go back to a previous version where it does. Further, you can dig into the release history and see what changes were made to Chrome that may have caused the errors.

A version control system allows you to do this, its like a long series of placeholders for your files. As you are programming (altering files) you are leaving a trail of crumbs incase you get lost or something goes wrong. The record is always there for you to see, and at any time you can retrace your steps to where you were before things got ugly. Of course version control offeres several other benifits besides this, most notable being able to collaborate asyncronously with other developers, branching features out of the main history to allow you to work without messing up the main codebase, and allowing for tagging and release cycles. But for now think of version control and git as a working history of your efforts.

Lets git to it. *gunshot*

Open a terminal window and navigate to your ~/lessons/basic-html directory (or wherever you decided to keep your html file from the previous lesson.) Make sure you see the file when you ls.

$>ls
index.html
The first time you run git, it may complain that you have not setup your identity. It is a good idea to go ahead and do so, so that you can be identified in the logs. Your name and email can be whatever you want.
Initialize

Now we need to tell git that we want to place the contents of our current directory under version control. This is something that only needs to happen once. We do this by running

$>git init
Initialized empty Git repository in /home/<username>/lessons/basic-html/.git/

This has created and empty repository in our ~/lessons/basic-html directory. A useful git command that I encourage you to run often is git status. It will give you the current state of the repository that manages the directory you are in (if one exists).

$>git status
On branch master

Initial commit

Untracked files:
  (use "git add <file>..." to include in what will be committed)

	index.html

nothing added to commit but untracked files present (use "git add" to track)

This tells us that our repository has been created, and we are on the first commit. It also mentions what branch we are on. Typically the default branch is master. For now we won’t worry too much about branches, just know we are working with the master branch.

Add

You can see in out status report that our index.html file is untracked. This means that it is not yet under version control. The status message gives the advice to add the file so we can include it in the next commit. We can do so by running:

$>git add index.html

$>git status
On branch master

Initial commit

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

	new file:   index.html

Our index.html file is now ready (staged) to be committed.

If you have a lot of files to add you can run git add -A to stage everything for the next commit.
Commit

Think of commits as a page in your working histroy. Commits are the bread and butter of version control. These are the markers that you can go back to, your crumb trail in the forest. When your files have reached a state that is notable, you should do a commit. The initial commit kicks everything off. All of your files should be added, and we mark this as the starting point of our working history. Each commit must have an accompanying commit message. This is usually a short blurb describing what changes have happened. We can do this all in one command with the -m option.

$>git commit -m"initial commit"
[master (root-commit) 5cc9a38] initial commit
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 index.html

$>git status
On branch master
nothing to commit, working directory clean

Commits should be made whenever there are clear divisions of work being done, or at landmark places you would like to remember. You have just completed a small task or feature, commit. You’ve cleaned up spacing in your code, commit. You’ve added a bunch of comments to your code, good for you, commit! You’ve done some file restructuring in your directory, commit. You finally debugged that weird problem, commit! You get the idea…​ It is better to commit too much than to little, use them liberally and keep the messages short but meaningful. Remember, each commit is a single crumb in your breadcrumb trail.

As an example of this workflow, open your index.html file in your text editor, and make some changes. It’s not important what you change, just change something. Add a new <h2> text, remove some paragraphs, etc. When you are done save your changes and jump back to your terminal window.

$>git status
On branch master
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   index.html

no changes added to commit (use "git add" and/or "git commit -a")

git status once again is full of helpful information. You can see that git is aware that we have modified our file, and is giving us a suggestion if we wish to commit those changes. You can do like we did before and run git add index.html followed by git commit -m"some message" but for modifications we can do it all in one command.

$>git commit -am"changes to html"
[master 43a2ee6] changes to html
 1 file changed, 1 insertion(+)

Now it’s just rinse and repeat as you work, comitting at notable times. I know it seems like this may be more effort initially, but the benifits are very real, and will become clear as you use git more and as we move forward.

GitHub

As I mentioned previously, GitHub is a service that allows you to host and manage remote repositories. Up to this point we have been working with a local repository, that you created on your system. Often times this may be all you need. I find myself creating and keeping a repository local when I am writing small proof of concept applications, or fiddling with a side project that is starting to become more complex. Just having your local repository is great for that. However, as your work grows in complexity and importance, or has a need for collaboration, It becomes important to both have a backup of your repository as well as a means to remotely access it. Github does that for us.

Before continuing, I highly suggest you setup an ssh key with GitHub. You can find instructions to do so here.

Pushing to a remote

Our end goal here is to post our fancy html code to GitHub. We already have our code in a local repository, now we need to create a remote GitHub repository. GitHub makes this very easy to do. After logging into github.com click the bright green button that says "+New Repository" in the right sidebar (if you are having a hard time finding it you can navigate there directly.) You should now see a form asking for some information about your new repository. Gve it a name like basic-html, and a description if you like. Be sure that the "Initialize this repository with a README" checkbox is not checked, as we are going to import the local repository we just created. Double check everything and click "Create Repository."

You should now be on your repository page. There isn’t much to see yet, because for the moment your newly created github repository is empty. Lets change that! GitHub provides some good instruction here, and we will be using the second scenario the list "…or push an existing repository from the command line." So jump back to your terminal window, and makes sure you are still in the directory where we created our local repository. Then simply follow the instructions GitHub provides. Something like:

$>git remote add origin git@github.com:<github-username>/basic-html.git

$>git push -u origin master
Counting objects: 6, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (6/6), 422 bytes | 0 bytes/s, done.
Total 6 (delta 0), reused 0 (delta 0)
To git@github.com:<github-username>/basic-html.git
 * [new branch]      master -> master
Branch master set up to track remote branch master from origin

By running these commands on your local repository you have done a couple things. The first command says to add a remote repository (called origin) and point it at our newly created github repository. The second command says to push local commits (remember making those) to origin (the remote repository) on branch master.

If you are curious the -u option in the push command is short for "set upstream tracking" and tells git that the remote branch you pushed to will track the branch you pushed from. Since we are only dealing with one branch (master) this isn’t so important. You don’t need to include the -u in any subsiquent pushes

So after running these commands, if everything went well, refresh the repository page in your browser and you should see your spiffy index.html file sitting on the screen. Check out the information on this page, and click around and explore a bit. GitHub shows a lot of information about the state of your (remote) repository, and is a great way to review commits, and see just what’s going on.

README.md

If you’re still with me then GREAT JOB! You’ve done a lot. But things are still looking a little bare up on your github repository page. We need to create a README file to let the world know about our super sweet html file. Now you can of course just click the "Add a README" button and let github walk you through it, but I think it is worth while to create this file locally, and push it up to the repository. This will demonstrate a typical workflow when working with a remote.

Jump over to your text editor and create a new file. Do a "save as" and call it README.md and save it in your basic-html folder. The same place your index.html file is. The .md suffix denotes a markdown file. If you are not familiar with markdown, it’s simply a formatting shorthand. GitHub has its own flavor of markdown that you can review. So in your newly created file add some markdown content describing your awesome repository. Mess with it, and put whatever you want. Something like:

# Fresh Hot HTML YO!

Serverd up straight to you with *MAD* git stylings.

Be sure to save your file when you are done.

Now jump back to your terminal. Be sure you are sill in the basic-html directory, and check your git status. You know what to do from here! Do a git add on that sucker and commit with a thoughtful message.

When you have successfully done this and your git status is clean, you’re ready to push up to github. The command is the same as the last time.

$>git push origin master

After the command completes, go back to your browser and refresh your repository page. You should see your nice new readme file rendered in all it’s glory.

From here, take a little time and play with this workflow. Make some changes to the html file or the readme or both. Commit them and push them up to github. You don’t have to push one commit at a time, you can make several before you do a push. It still works the same way. Add other files if you want, and commit and push those. Just get used to the sequence:

  1. make changes

  2. add/commit

  3. repeat 1 and 2 until ready to share

  4. push to the remote

If you haven’t already continue to explore the repository page and the links therein. Especially note the "commits" link just above the branch dropdown. You can see your commit history log, and even drill down to view the actual changes.

Pshew!

This was a long one with a lot of information. Go slow and play around with it. Let things sink in a little bit. While you are messing around on github, go ahead and follow me https://github.com/rh0 it will let me know what your github username is, so I can start to look over your work as we progress. Dun dun dun…​.

comments powered by Disqus