A Magit Tutorial: Part I

I love Emacs. I only started using it a few months ago, but I'm already hopelessly in love with its (unapparent) simplicity and crazy extensibility. Perhaps my custom hand-crafted .emacs, -- yes, I call it hand-crafted -- alongwith the fact that this very blog post has been written in Emacs, is proof enough.

I recently came across Magit for Emacs, and I was amazed at how much it could do. It's basically a cool interface to git, inside Emacs. This post here is the first in a 2 part series that aims to be a reasonably comprehensive tutorial to using Magit (make sure you have it installed first, as per the instructions in the README here). However, it assumes prior familiarity with both Git and Emacs, so if you're not comfortable with either, this guide probably won't help you much. I have, however, listed some excellent git resources at the bottom of this article, so you can skip along to that part if you don't want to read the whole thing.

Starting Magit

The first command you need to know is M-x magit-status. So to see the status of a git repository using Magit, open a file in Emacs that is a part of that repository, and then run the above command. That is usually how I initiate interaction with Magit, so I've bound magit-status to C-x g s. This opens up a buffer with a name like *magit: blog* or something similar. This buffer is in magit-mode, with convenient keybindings for common git operations like staging and committing.

Sections in Magit buffers

Each Magit buffer is divided into tree-like sections, and each section can be hidden or shown individually. The <Tab> key toggles the visibility of a section. You can also use M-S (show all) and M-H (hide all). M-H collapses all diffs, so you can see at a glance the list of files involved, and M-S expands everything, so you can see full diffs of all the files. Sweet!

The Magit status buffer

The Magit status buffer is divided into sections as described above. The top header gives general information about the repository's current state (the current branch, the repository's location, and so on). The first section is Untracked Files, followed by sections for the staging area.

Untracked Files, Unstaged Changes and Staged Changes

The Untracked Files section lists all untracked files (duh). You can add an untracked file to the staging area using s (which will move it to the Staged Changes section), ignore it with i, or delete it permanently with k. If point is on the Untracked Files section header, pressing s or k will stage or delete all untracked files, respectively. Typing C-u S anywhere will stage all untracked files, alongwith all changes to already tracked files.

In the Unstaged Changes section, s will stage the change point is in, and S will stage all changes, regardless of the position of point. Similarly, in the Staged Changes section, u will unstage the change point is in, and U will unstage all changes, regardless of the position of point.

Oh, and you can even stage parts of changes individually! All you have to do is expand everything (M-S), navigate to the part of the file diff you want to stage (the region will get highlighted as you move into it), press s, and BAM! It doesn't get any cooler than that.

When you're done deciding which changes to stage, type c to open up a buffer to write your commit message in, and when you're done doing that, press C-c C-c to commit your changes. Congratulations, you've successfully performed your first commit in Magit! (Interestingly, Magit was used for the publication of this very blog post!)

That's it for the first part. Part II will pick up with how to view the git log in Magit and continue further from there.

UPDATE: Part II is now up!

Git Resources: