emacs.d/elpa/magit-20141114.934

It's Magit! An Emacs mode for Git

The Magit wiki contains a list of frequently asked questions, please do consult it.

Magit is an interface to the version control system Git, implemented as an Emacs extension.

Unlike the Version Control package which is part of Emacs and strives to provide a unified interface to various version control systems, Magit only supports Git and can therefore better take advantage of its native features.

Magit supports GNU Emacs 23.2 or later; 24.1 or later is recommended. Magit supports Git 1.7.2.5 or later; 1.8.2 or later is recommended. The minimal versions are those available in Debian oldstable.

Feature Freeze

There are currently three "versions" of Magit. The 1.2.1 bugfix release which is mostly the same as 1.2.0 released in 2012. The master branch, which the packages on Melpa and Melpa-Stable are built from. This hasn't seen many major changes since February of this year. And the next branch which contains 99% of the work I have done during the last eight months.

It's about time that next is merged and that a release is created. For that reason I am not going to implement any new features being proposed now, until after I have created a release. Magit isn't in a complete feature freeze yet, there are certain new features that I do want to be part of the next release.

No completely new features are going to be implemented until after the next release. However some "new" features are going to make it into the release which replace existing but broken and/or misguided features.

This shouldn't keep you from making feature requests, but first please check whether that feature already exists on next and don't expect it to be implemented until after the release. For instructions on how to install the next version of Magit see this and that.

Table of Contents

• Getting Started
• Getting Help
• Contributions
• Installation
  • Installing from Melpa
  • Installing from Marmalade
  • Installing from Git
  • Installing from Tarball
• Dependencies

Getting Started

To get started with Magit, run M-x magit-status. If you are inside a Git repository this opens a buffer that summarizes its status. Otherwise you are first prompted for a repository. Read the short help for magit-status-mode (C-h m in the status buffer).

Then edit and save some files, refresh the status buffer (g), stage changes (s) and commit (c) them.

For more details consult the Magit user manual. You can read it with C-u C-h i magit.info or on the web.

We can also recommend this introduction from the Mastering Emacs blog. It even describes some new features that are not yet documented in the manual.

Magit also has a website.

Getting Help

When something breaks please see the FAQ. If that doesn't help check the list of all open issues.

If everything else fails please open a new issue or ask for help on the mailing list.

Contributions

Magit is hosted on Github. Please contribute by suggesting features on the issue tracker or by making code contributions using pull requests. Before opening a pull request make sure to read the brief guidelines.

Please also consider supporting development using gratipay. Thank you!

Magit was started by Marius Vollmer and is now maintained by Jonas Bernoulli. Other Magitians (former maintainers) are Nicolas Dudebout, Peter J. Weisberg, Phil Jackson, Rémi Vanicat, and Yann Hodique.

Many more people have contributed code and suggested features.

Thanks to all of you, may (the history of) the source be with you!

Installation

Beginning with version 24.1 Emacs includes a package management facility known as Elpa or package.el. Using an Elpa package repository is the easiest and recommended way to install and update Magit and its dependencies. Among other things using package.el is recommended because that automatically takes care of installing dependencies.

Magit is available from both of the two popular Elpa repositories, Marmalade (stable releases) and Melpa (snapshots).

Installing from Melpa

If you have already used Melpa to install some other package then all you have to do is:

M-x package-install RET magit RET

This installs Magit as well as all of its dependencies and makes them available in the current and future Emacs sessions.

If this is the first time you are using Melpa, then you have to configure package.el once.

(require 'package)
(add-to-list 'package-archives
             '("melpa" . "http://melpa.milkbox.net/packages/") t)

Then evaluate these forms, update the package cache, and install Magit as above. To update the cache use:

M-x package-refresh-contents RET

You might also want to have a look at the more detailed instructions provided by the Melpa project. Among other things it explains how to install only some packages from Melpa and others from Marmalade, and how to use package.el with older versions of Emacs.

Installing from Marmalade

For the time being we recommend that you install the development version available from Melpa, because the latest Magit release (which is what you get from Marmalade) is very outdated. If you are using the development version of Emacs, then you have to do so, because it contains an incompatible change that breaks the last Magit release.

Installing from Git

If you want to contribute to Magit you should run it directly from the Git repository.

First get the repository:

$ git clone git://github.com/magit/magit.git

Then you should byte compile the libraries and generate the documentation, though that is not required:

$ make lisp docs

Unless all dependencies are installed at ../DEPENDENCY you have to tell make where to find them, e.g.:

$ EFLAGS="-L /path/to/git-modes" make lisp docs

Then add this to you init file:

(add-to-list 'load-path "/path/to/git-modes")
(add-to-list 'load-path "/path/to/magit")
(eval-after-load 'info
  '(progn (info-initialize)
          (add-to-list 'Info-directory-list "/path/to/magit/")))
(require 'magit)

If you are using an Emacs version before 24.3, then you also have to install cl-lib and tell make as well as Emacs where to find it.

To view available make targets use:

$ make help

To update use:

$ git pull
$ make lisp docs

Before creating a pull request always run:

$ make lisp test

You may also build Magit manually:

$ emacs -Q --batch -L . -L /path/to/DEPENCENCY -f batch-byte-compile *.el
$ makeinfo -o magit.info magit.texi
$ install-info --dir=dir magit.info

Installing from Tarball

This is only intended for users who have been doing this sort of thing for years. Installing from a tarball isn't particularly difficult but because we are only providing this as an alternative method we are a bit light on documentation, so it helps to have done this before.

Also most steps have to be repeated every time you want to update.

Because the latest Magit release is very outdated, please consider installing the development version even if tarballs are your thing.

Download and unpack magit-1.2.1.tar.gz. Then build and install as usual:

$ wget https://github.com/magit/magit/releases/download/1.2.1/magit-1.2.1.tar.gz
$ tar -xf magit-1.2.1.tar.gz
$ cd magit-1.2.1
$ make
$ sudo make install

This installs the Emacs lisp libraries, as well as the prebuilt documentation from the tarball. You may alternatively build the documentation yourself:

$ make docs
$ sudo make install-docs

By default the Emacs lisp libraries are installed in /usr/local/share/emacs/site-lisp/magit/. Unless Emacs itself is also installed in /usr/local/ you have to add that directory to the load-path.

(add-to-list 'load-path "/usr/local/share/emacs/site-lisp/magit")

Then magit can be loaded:

(require 'magit)

Add the above lines to your init file and restart Emacs.

Dependencies

If you install Magit using package.el then dependencies are automatically being taken care of. Otherwise you have to track down dependencies and install them manually.

• cl-lib is a new library in Emacs 24.3. Like the old cl it provides various Common Lisp forms, but differs in that symbols are prefixed with cl-. A forward compatibility cl-lib for older versions of Emacs is available from the GNU Elpa repository. You can install it using package.el or get it here.

• git-commit-mode which is part of the git-modes repository and available as a separate package from Melpa.

• git-rebase-mode which is part of the git-modes repository and available as a separate package from Melpa.

Optional Dependencies

The following libraries build on third-party tools or git subcommands that are not installed by the Git base-package on some distributions:

• magit-stgit.el requires stgit.
• magit-svn.el requires the official Git subcommand svn.
• magit-topgit.el requires topgit.
• magit-wip.el requires git-wip.

Dependencies of Tests

To run tests the following libraries are also required:

• ert is a tool for automated testing. It is part of Emacs starting with version 24.1. You can also obtain an old version from the former development repository.