Using the At-Sign for Git Revisions

Today I want to share some simple tips for how you can refer to revisions in Git. Revisions most often refer to commits, but not always. But for the sake of simplicity we will assume that you only want to use the revision syntax to name commits; if you have a reason to name other Git objects like trees then you probably already know what I’m about to write.

Note: In the middle of the week I was asked by a publisher to review an upcoming book about Lua game programming, so my apologies for not writing about my usual ‘Book of the Week’ on Sundays.

Common Revision Syntax

The most precise way to refer to any revision is via its SHA-1 hash, e.g. git show 54c2fb20ae154f0797ca02308ab8e52001bdac8b. You can abbreviate this as much as you want so long as Git can still recognize the unique revision. In my experience using the first eight characters of the hash works fine, so I shorten commands like the above to git show 54c2fb20. That command would only confuse Git if another revision also begins with 54c2fb20, which is a problem I do not think I’ve ever had.

Another syntax I often use is the output from the git-describe command. It is useful for repositories that use tagging.

However, as the title indicates, I want to focus on the revision syntax that uses the @ character. The general syntax is <refname>@{…}, e.g. master@{yesterday}. If you do not provide a refname then Git will use HEAD by default.

That example shows a useful application of the at-sign syntax: referring to revisions based on time and/or date. For example, what if I want to see all of the commits on the master branch over the course of the previous month? I can use git log --since master@{one month ago}. There is a lot of flexibility in how you can phrase the time and most natural expressions will work as expected. As another example, git log --since @{2013-01-01} or git log --since @{1 January 2013}; the both accomplish the same.

Sometimes you may want to refer to revisions relative to the current one, and for this you can use the @{N} syntax where N is an integer representing the N-th commit from the current. That means @{1} is the commit immediately before the current, @{2} is the one before that, and so on. Run the command git-reflog to see an example of this syntax.

The final syntax I want to mention is @{upstream}, or @{u} for short. This is a shortcut for referring to the remote upstream of the current branch. So for example, after fetching updates I like to do git merge --ff-only @{u} to merge those changes. Or run git log ..@{u} to see the commits I am about to merge.

Conclusion

The at-sign syntax is useful for referring to revisions, as I hope you agree. For more examples and detailed information see the official Git documentation about revisions.

Advertisements

Add Your Thoughts

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s