Next: , Previous: , Up: Top   [Contents][Index]

3 Getting started

This section describes the most essential features that many Magitians use on a daily basis. It only scratches the surface but should be enough to get you started.

(You might want to create a repository just for this walk-through, e.g. by cloning an existing repository. If you don’t use a separate repository then make sure you create a snapshot as described below).

To display information about the current Git repository, type M-x magit-status. You will be doing that so often that it is best to bind this command globally:

(global-set-key (kbd "C-x g") 'magit-status)

Most Magit commands are commonly invoked from this buffer. It should be considered the primary interface to interact with Git using Magit. There are many other Magit buffers, but they are usually created from this buffer.

Depending on what state your repository is in, this buffer will contain sections titled "Staged changes", "Unstaged changes", "Unpulled commits", "Unpushed commits", and/or some others.

If some staged and/or unstaged changes exist, you should back them up now. Type z to show the stashing popup buffer featuring various stash variants and arguments that can be passed to these commands. Do not worry about those for now, just type Z (uppercase) to create a stash while also keeping the index and work tree intact. The status buffer should now also contain a section titled "Stashes".

Otherwise, if there are no uncommitted changes, you should create some now by editing and saving some of the tracked files. Then go back to the status buffer, while at the same time refreshing it, by typing C-x g. (When the status buffer, or any Magit buffer for that matter, is the current buffer, then you can also use just g to refresh it).

Move between sections using p and n. Note that the bodies of some sections are hidden. Type TAB to expand or collapse the section at point. You can also use C-tab to cycle the visibility of the current section and its children. Move to a file section inside the section named "Unstaged changes" and type s to stage the changes you have made to that file. That file now appears under "Staged changes".

Magit can stage and unstage individual hunks, not just complete files. Move to the file you have just staged, expand it using TAB, move to one of the hunks using n, and unstage just that by typing u. Note how the staging (s) and unstaging (u) commands operate on the change at point. Many other commands behave the same way.

You can also un-/stage just part of a hunk. Inside the body of a hunk section (move there using C-n), set the mark using C-SPC and move down until some added and removed lines fall inside the region but not all of them. Again type s to stage.

It’s also possible to un-/stage multiple files at once. Move to a file section, type C-SPC, move to the next file using n, and then s to stage both files. Note that both the mark and point have to be on the headings of sibling sections for this to work. If the region looks like it does in other buffers, then it doesn’t select Magit sections that can be acted on as a unit.

And then of course you want to commit your changes. Type c. This shows the committing popup buffer featuring various commit variants and arguments that can be passed to git commit. Do not worry about those for now. We want to create a "normal" commit, which is done by typing c again.

Now two new buffers appear. One is for writing the commit message, the other shows a diff with the changes that are about to committed. Write a message and then type C-c C-c to actually create the commit.

You probably don’t want to push the commit you just created because you just committed some random changes, but if that is not the case you could push it by typing P to bring up the push popup and then u to push to the configured upstream. (If the upstream is not configured, then you would be prompted for the push target instead.)

Instead we are going to undo the changes made so far. Bring up the log for the current branch by typing l l, move to the last commit created before starting with this walk through using n, and do a hard reset using C-u x. WARNING: this discards all uncommitted changes. If you did not follow the advice about using a separate repository for these experiments and did not create a snapshot of uncommitted changes before starting to try out Magit, then don’t do this.

So far we have mentioned the commit, push, and log popups. These are probably among the popups you will be using the most, but many others exist. To show a popup with all other popups (as well as the various apply commands), type h. Try a few.

The key bindings in that popup correspond to the bindings in Magit buffers, including but not limited to the status buffer. So you could type h d to bring up the diff popup, but once you remember that "d" stands for "diff", you would usually do so by just typing d. But the "popup of popups" is useful even once you have memorized all the bindings, as it can provide easy access to Magit commands from non-Magit buffers. So you should bind this globally too:

(global-set-key (kbd "C-x M-g") 'magit-dispatch-popup)

You might also want to enable global-magit-file-mode (see Minor mode for buffers visiting files).

Next: , Previous: , Up: Top   [Contents][Index]