Hack ↺ Repeat

From zero to git, episode 2: Branching, merging and tagging

2011-10-07T00:00:00+02:00

In this post I’ll further expand the basic git usage with branches and tags (previous: ”git daily disconnected commands”).

Good habits: local branching

Do you remember the practical advice about when to commit from the previous article? Sometimes just committing is not enough, for example “when you are about to start something you feel like you may regret” because in case you actually regret your actions, you have to dig with git log to find the id of the precise commit you want to go back to (remember that 7c628c78707a76b11a70716ad082da621047afe2?). It’s not difficult, but we can do better with branches.

Show me the branches

A branch is just a label that automatically follows your commits: you already have one that is following you, but you don’t know: it is called master.

$ git branch
* master

The branch command shows your local branches. The current active branch (the one that is checked-out and you see as your working directory) is displayed with an * ahead of it. As I said there’s already one and since you have it checked-out, every time you commit, master moves to point to that last commit.

Branch it

Now I want to put some changes in my project. Maybe it’s something experimental, and I want to have a safe fallback to the current revision, waiting for me under a named label.

From the current branch (in this case master), we checkout an exact copy under another label so that the current label stays on the last commit it was attached to (in this case this will be our safe fallback).

$ git checkout -b something-I-will-regret
Switched to a new branch 'something-I-will-regret'
$ git branch
  master
* something-I-will-regret

The checkout command is used to pick something in the git history and put it in the working copy. The -b option is used to create a new branch (based on the contents of the current one) under the branch name specified after -b (something-I-will-regret, in this case) and, after that, putting that branch in the working copy (or more intuitively, switching you to the newly created branch).

Now at each commit, the checked-out branch (you can’t check out more than one at a time) will follow us, while any other non checked-out branch will stay still, pointing the commits they were on the last time they moved.

Remembering what we learned in the previous article, we can work on the something that we will regret. For this example, modify something, add it to the index and commit it.

$ # file modified
$ git status 
# On branch something-I-will-regret
# 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:   due.txt
#
$ git commit -m"Fixed a bad mistake"
[something-I-will-regret 05da584] Fixed a bad mistake
 1 files changed, 1 insertions(+), 1 deletions(-)

Change, add and commit any time you want, then we will move back.

Moving between branches

Now is the time we regret the correction, so we want to go back: we already know the command that we need: checkout.

$ git checkout master 
Switched to branch 'master'

The same command we used before to “switch” to the something-I-will-regret branch, but this time we didn’t need the -b because we wanted to get to an existing branch.

If you watch your files you’ll notice that they are back to the state they were on the last commit we did on master branch. Finally we know that git didn’t lie to us :D.

Notice that the branch named something-I-will-regret is still there, and all the commits you did under that name are there, too.

You know what? I changed my mind again. The something-I-will-regret branch was not that bad. Let’s merge it back into master branch.

Fast-forward merge

What we are going to do now is a very special case of merging. This will happen just because after branching (git checkout -b something-I-will-regret) we haven’t changed anything in the master branch. The effect is that master was just behind something-I-will-regret, but the two never really diverged.

We are going to lose the previous position of our master, making it point to the same commit that something-I-will-regret is pointing to (hence fast-forward).

$ git merge something-I-will-regret 
Updating 879611a..05da584
Fast-forward
 due.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

With the merge command in this case you are merging the state of the branch specified in the command (something-I-will-regret) into the current branch (master).

Now that we are sure that all went well, we don’t need the something-I-will-regret anymore, so we delete it: if you are on something-I-will-regret, checkout another branch (e.g. master).

$ git branch
* master
  something-I-will-regret
$ git branch -d something-I-will-regret
Deleted branch something-I-will-regret (was 05da584).
$ git branch
* master

-d means delete obviously. If we didn’t merge and simply wanted to discard the changes made in something-I-will-regret restarting to work on what we had in master, from the master branch, this is the command: git branch -D something-I-will-regret. It’s very similar to the previous one, but -D uses a capital “d”. This difference avoid that you delete branches that are “not fully merged”, use carefully.

Now you can create new branches, work on them, discard changes by moving back, accept changes by fast forwarding. Cool.

Appendix: Something about objects

We talked a lot about commit. Git records commits as commit objects. This object stores informations like:

the date
a reference to an object representing the state of the files
references to other commits objects, the parents of the current commit

I think it’s useful to stress something about the last point, in particular if this is your first time using a revision control system: since the commits specify moments in history, we also need to put them together in a coherent flow. That commit references point to the parents of this commit (usually it’s just one parent, though).

This references creates a graph that represents the history of the repository. In the examples we’ve seen so far it’s more like a sequence (this should be clear looking at the little graph images in this post).

Conclusion

Here is a recap on the commands we saw in this article:

$ git branch # shows local branch situation
$ git checkout -b branch-name # creates a branch based on the contents of the current checked out state and switches to it
$ git checkout branch-name # switches to the named branch. The current status should be clean to do this
$ git merge branch-name # merges changes committed in the named branch into the current checked out branch
$ git branch -d branch-name # delete a branch (i.e. the label) safely
$ git branch -D branch-name # delete a branch (i.e. the label) unsafely (unmerged changes will be discarded)
$ git tag tag-name # create a lightweight tag

You are now able to work with git trying new things without leaving your files in a bad state (with tags and branching). In the next episode we will see some situations where merging is not automatic , something that happens more frequently when multiple people work on a project but that can prove useful even when working alone. Now that you are a git user you can’t miss it :D.

From zero to git, episode 1: Daily disconnected git commands

2011-10-06T00:00:00+02:00

This article is part of a very practical experimental series that aims to teach git to novices, without forcing git theory right away.

In this article I’ll try to show you the bare minimum commands (four commands in this article) needed to start using git assuming that:

you have lots of copies of your projects directories named like this: project_old and project_new_feature and project_20110611 and you hate them
you just want to start to track your file changes
you don’t need to use a remote server to backup or share your local repository (you are working alone on your project)
you don’t use a GUI, just the command line
you have created a local empty repository

I suggest that you follow the little example I will show you, typing all the commands yourself. This will make it easier to learn the basics that are contained in this article. Once you get to the end, you’ll find a little recap on the commands you used, in case you want to review them when starting to work on your own project.

The status

Now that we have a local repository we will start with the daily operations: we will start “inspecting” its current status with the status command:

$ git status
# On branch master
#
# Initial commit
#
nothing to commit (create/copy files and use "git add" to track)

This is probably the most used git command, we will see various kinds of output from this command.

Tracking files

Now, we can put some file in it. At this point, if you have an existing project you can put your project files in the repo’s directory, but for the sake of this tutorial we will create something form scratch.

Let’s create a file and re-run the status command:

$ echo bazbar > uno.txt
$ git status
# On branch master
#
# Initial commit
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#	uno.txt
nothing added to commit but untracked files present (use "git add" to track)

Contrary to other systems, Git doesn’t track blindly anything you change in the working directory, so we have to introduce the concept of index, that is just a list of the things you want to put in the repository’s history next.

I created a file named uno.txt: the status command now shows that we have “untracked files”. What we want to do is to add the files we want to be tracked to our repository’s index. As suggested by the previous output itself, we will use the add command to put the file in the index, ready to be tracked:

$ git add uno.txt
$ git status 
# On branch master
#
# Initial commit
#
# Changes to be committed:
#   (use "git rm --cached <file>..." to unstage)
#
#	new file:   uno.txt
#

With the add command we can add single files (as we did with uno.txt), multiple files (as we will see in a following paragraph) or entire directories.

Now we have a file staged in the git index that means that it is selected to be tracked by git: next we have to record this very state of the index as a commit.

What not to add

Not every file has to be included in your repository. Files containing passwords and other sensible data, most generated files (e.g. binary executables) should not be included in a repository. To exclude them automatically before ever adding them you can create a .gitignore file at the root of your repository.

See ”Ignoring files” from the git-book to learn how to use a .gitignore file. See gitignore project on github as a starting point for many programming-related gitignore templates.

Freezing a moment in history: the commit

Now that we decided what we want to be recorded (that is what we decided to add to the index), we need to use the commit command to create a snapshot of the current state of our files.

$ git commit -m"Added bazbar to fix the lack of it"
[master (root-commit) 7c628c7] Added bazbar to fix the lack of it
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 uno.txt

(You can put a space between the -m and the “Message” if you prefer).

The command I used has a -m option attached to it: m stands for “commit message”, that is a non optional part of the commit object itself: a commit object is one of the object types stored in your .git directory (the actual repository) that is used to keep track of the pieces of information about a revision. If you don’t add the message in the commit command, git will launch your text editor for you to type the message: saving and closing will finalize the commit.

Practical-advice moment: when to commit?

Quite often, if you ask me. Actually it’s something you have to work out yourself but the general advice is valid since git tends to maintain your repo compact in size: it’s not like having a copy of your contents for every change, it’s far far less.

So when you are about to start something you feel like you may regret, think about committing (and, when you will know git better, branching); when you accomplished something you can describe compactly in a commit message, think about committing.

The idea is that you should avoid a big fat commit at the end of the day, even if you just worked all day on a single aspect of your project: much better having at least two-three commits, the more the better, just don’t fall to the other side (90 commits a day may be simply too much of them :D).

Captain’s log, stardate 7c628c7

Now we will make another commit: open uno.txt, change something (add a line, change something that is already there, …), save uno.txt and create a file named due.txt with something in it.

The result of git status shows due.txt as an untracked file, and uno.txt in modified state.

Now it’s just identical to what we’ve done previously starting with the ”Tracking files” paragraph, so add (to the index) anything you want to be in your next commit, for example:

$ git add uno.txt due.txt

to add both files (this is the way to add multiple files at once, space separated; alternatively you can run several subsequent git add commands and get the same result).

After that, commit with a message.

Now that we have a proper history of commits, let’s visualize it (note that this command works also with just one commit): meet the log command:

$ git log
commit 879611a6e5b9b8f20aed15c62c82c432fdf188a0
Author: Matteo Scotuzzi <matteo.scotuzzi@...>
Date:   Thu Oct 6 14:59:48 2011 +0200

    Committing changes and a new file at once

commit 7c628c78707a76b11a70716ad082da621047afe2
Author: Matteo Scotuzzi <matteo.scotuzzi@...>
Date:   Sun Oct 2 15:16:47 2011 +0200

    Added bazbar to fix the lack of it

Note: if the list of commit is longer than the terminal’s height you can navigate up/down with keyboard keys (internally uses less command to display). To go back to your terminal, press q.

What’s that? It’s your git captain’s log! It displays the commits in reverse chronological order (like in blog posts, the last is at the top of the list).

This log will be valuable to remember the last step of your project (assuming you wrote good commit messages) and is necessary to get the id of the commits in case you need it: each commit has a SHA-1 hash string like 7c628c78707a76b11a70716ad082da621047afe2 that identifies uniquely the (contents of the) commit itself. We will see in a future article how this information can come in handy.

Conclusion

Here is a recap on the commands we saw in this article:

$ # in the working directory of an existing repository
$ git status
$ # work work work
$ git status
$ git add your-work
$ git commit -m"Some cool work"
$ # more work
$ git add more-work
$ git commit -m"more work"
$ git log
$ # admire your work

At this point you can continue to work re-starting with ”The status” paragraph. You are now recording steps in your work and that’s a good accomplishment! But what if you screw up? You need to go back, but you’ll notice that you don’t know how to do so! The next post, branching, merging and tagging is what you need.

From zero to git, episode 0: first things first

2011-10-06T00:00:00+02:00

So, you want to do version control with git on your files? But let’s admit it: git it’s not all that straight forward for a novice.

Lots of git explanations you can find on the internet start with a fair share of git internal concepts. I think this is not the one-size-fits-all solution, so I started to write this series of articles as an experiment in which you learn some practical command to get started and then you are exposed to the theory. Let’s see how much damage I can do :D.

This article shows you two occasional git commands to get you started. It assumes that:

you already installed git

Once in a while: presenting yourself

First of all let’s present ourselves to git:

Type the following commands, editing the last part to fit your case

$ git config --global user.name "Your Name"
$ git config --global user.email you@example.com

All the previous needs to be done once, especially if you backup your setting files when changing computer, so there’s no real need to remember.

Once on new project: empty repository

The first thing to start working with git is getting some repository. For the purpose of this series of articles we will start from scratch.

Like the previous one, this operation is not really something you will do daily, but it happens more times than setting your name.

Using your terminal, get in the empty directory (create one if you haven’t one yet) that will hold your repository. Type:

$ git init
Initialized empty Git repository in <directory>/.git/

<directory> is the absolute path of your git repository. At that path a hidden .git directory is added. This is where the actual repository is stored, the files you will actually work with are outside the .git dir and are just your current working copy.

The .git directory is very important, you don’t want to mess with it without knowing what you are doing.

Bonus: two nice settings

I highly recommend this one, as it will make easier to interpret the command line output at a glance:

$ git config --global color.ui true

A second nice tip (specific for bash) is slightly more difficult to add, but is well worth it. Is used to show information about the state of your files to the bash prompt, you will appreciate this in the episode of this series about branches (branching, merging and tagging).

Open the ~/.bashrc file and add the lines below (appending them at the end should be fine).

#Checks if the current git branch is in a dirty state (uncommitted work)
function parse_git_dirty {
  [[ $(git status 2> /dev/null | tail -n1) != "nothing to commit (working directory clean)" ]] && echo "*"
}

PS1='${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]$(__git_ps1 " (%s$(parse_git_dirty))")\$ '

If you don’t have ~/.bashrc and are on a unix operating system you may have to find the right place for this yourself (it’s probably ~/.bash_profile).

Done :D. Don’t miss the daily bare minimum git commands in the next article.

Hack ↺ Repeat

From zero to git, episode 2: Branching, merging and tagging

Good habits: local branching

Show me the branches

Branch it

Moving between branches

Fast-forward merge

Tags

Appendix: Something about objects

Conclusion

From zero to git, episode 1: Daily disconnected git commands

The status

Tracking files

What not to add

Freezing a moment in history: the commit

Practical-advice moment: when to commit?

Captain’s log, stardate 7c628c7

Conclusion

From zero to git, episode 0: first things first

Once in a while: presenting yourself

Once on new project: empty repository

Bonus: two nice settings