312 lines
12 KiB
Text
312 lines
12 KiB
Text
\input texinfo.tex @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename magit.info
|
|
@settitle Magit User Manual
|
|
@c %**end of header
|
|
|
|
@dircategory Emacs
|
|
@direntry
|
|
* Magit: (magit). Using Git from Emacs with Magit.
|
|
@end direntry
|
|
|
|
@copying
|
|
Copyright @copyright{} 2008 Marius Vollmer
|
|
|
|
@quotation
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.2 or
|
|
any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
|
Texts.
|
|
@end quotation
|
|
@end copying
|
|
|
|
@node Top
|
|
@top Magit User Manual
|
|
|
|
Magit is an interface to the version control system Git, implemented
|
|
as an extension to Emacs.
|
|
|
|
@menu
|
|
* Introduction::
|
|
* Acknowledgments::
|
|
* Status::
|
|
* History::
|
|
* Diffing::
|
|
* Resetting::
|
|
* Branching::
|
|
* Merging::
|
|
* Rebasing::
|
|
* Pushing and Pulling::
|
|
@end menu
|
|
|
|
@node Introduction
|
|
@chapter Introduction
|
|
|
|
With Magit, you can inspect and modify any number of Git repositories.
|
|
You can review and commit the changes you have made to the tracked
|
|
files, for example, and you can browse the history of past changes.
|
|
|
|
Magit is not a complete interface to Git, it just makes the most
|
|
common Git command-line tools more convenient to use. Thus, while
|
|
Magit is a good way to experiment with Git, it will not save you from
|
|
learning Git itself.
|
|
|
|
This manual provides a tour of all Magit features. It does not give a
|
|
introduction to version control in general, or to Git in particular.
|
|
|
|
The main entry point to Magit is @kbd{M-x magit-status}, which will
|
|
put you in Magit's status buffer. You will be using it frequently, so
|
|
it is probably a good idea to bind @code{magit-status} to a key of
|
|
your choice.
|
|
|
|
In addition to the status buffer, Magit will also create buffers that
|
|
show lists of commits, buffers with diffs, and other kinds of buffers.
|
|
All these buffers are in @code{magit-mode} and have the same key
|
|
bindings. Not all commands make sense in all contexts, but a given
|
|
key will always do the same thing.
|
|
|
|
@node Acknowledgments
|
|
@chapter Acknowledgments
|
|
|
|
From day one of the first Magit announcement, John Wiegley, Linh Dang,
|
|
and Christian Neukirchen have contributed fixes, UI improvements, and
|
|
new features. Thanks!
|
|
|
|
Phil Hagelberg joined a few days later. Thanks!
|
|
|
|
@node Status
|
|
@chapter Status
|
|
|
|
Running @kbd{M-x magit-status} displays the main interface of Magit,
|
|
the status buffer.
|
|
|
|
You can have multiple status buffers active at the same time, each
|
|
associated with its own Git repository. Running @code{magit-status}
|
|
in a buffer will display the status buffer for the repository that
|
|
contains the file in that buffer. Running @code{magit-status} outside
|
|
of any Git repository or when giving it a prefix argument will ask you
|
|
for the directory to run it in.
|
|
|
|
You need to explicitly refresh the status buffer when you have made
|
|
changes to the repository from outside of Emacs. You can type @kbd{g}
|
|
in the status buffer itself, or just use @kbd{M-x magit-status}
|
|
instead of @kbd{C-x b} when switching to it. You also need to refresh
|
|
the status buffer in this way after saving a file in Emacs.
|
|
|
|
The header at the top of the status buffer shows a short summary of
|
|
the repository state: where it is located, which branch is checked
|
|
out, etc. Below the header are up to four sections that show details
|
|
about the working tree and the staging area. Only sections that are
|
|
not empty are shown.
|
|
|
|
The first of these sections lists @emph{Untracked files}. These are
|
|
the files that are present in your working tree but are not known to
|
|
Git; they are neither tracked in the current branch nor explicitly
|
|
ignored. You can move point to one of the listed files and type
|
|
@kbd{s} to add it to the staging area. Or you can tell Git to ignore
|
|
the file by typing @kbd{i}.
|
|
|
|
Magit has no shortcuts for removing or renaming files. You need to
|
|
use @code{git rm} or @code{git mv} in a shell and then refresh the
|
|
status buffer.
|
|
|
|
The next section, named @emph{Unstaged changes}, shows the differences
|
|
between the working tree and the staging area. Thus, it shows the
|
|
modifications that have not been staged yet and would thus not be
|
|
included if you would commit now.
|
|
|
|
The next section, @emph{Staged changes}, shows the differences between
|
|
the staging area and the current head. These are the changes that
|
|
would be included if you would commit now.
|
|
|
|
Unlike other version control interfaces, Magit does not usually
|
|
operate on files: Instead of dealing with files (or sets of files),
|
|
differences are shown as diffs and you deal with the individual hunks.
|
|
|
|
Normally, you will prepare the staging area so that it contains
|
|
changes that you want to commit as a unit. You can leave changes that
|
|
you are not yet ready to commit safely out of the staging area.
|
|
|
|
To move a hunk from the working tree into the staging area, move point
|
|
into the hunk and type @kbd{s}. Likewise, to unstage a hunk, move
|
|
point into it and type @kbd{u}. If point is in a diff header when you
|
|
type @kbd{s} or @kbd{u}, all hunks belonging to that diff are moved at
|
|
the same time. To move all hunks of all diffs into the staging area
|
|
in one go, type @kbd{S}. To unstage everything, type @kbd{U}.
|
|
|
|
Before committing the changes in the staging area, you should write a
|
|
short description of them.
|
|
|
|
Type @kbd{c} to pop up a buffer where you can write your change
|
|
description. Once you are happy with the description, type @kbd{C-c
|
|
C-c} in that buffer to commit the staged changes.
|
|
|
|
Typing @kbd{C} will also pop up the change description buffer, but in
|
|
addition, it will try to insert a ChangeLog-style entry for the change
|
|
that point is in.
|
|
|
|
If the current branch is associated with a remote repository, the
|
|
status buffer will show a fourth section, named @emph{Unpushed
|
|
commits}. It will briefly list the commits that you have made in your
|
|
local repository, but have not yet pushed. See @ref{Pushing and
|
|
Pulling} for more information.
|
|
|
|
@node History
|
|
@chapter History
|
|
|
|
To show the repository history of your current head, type @kbd{l}. A
|
|
new buffer will be shown that displays the history in a terse form.
|
|
The first paragraph of each commit message is displayed, next to a
|
|
representation of the relationships between commits.
|
|
|
|
Typing @kbd{L} will ask for the starting and end point of the history.
|
|
This can be used to show the commits that are in one branch, but not
|
|
in another, for example.
|
|
|
|
You can move point to a commit and then cause various things to happen
|
|
with it. (The following commands work in any list of commit, such as
|
|
the one shown in the @emph{Unpushed commits} section.)
|
|
|
|
Typing @kbd{RET} will pop up more information about the current
|
|
commit.
|
|
|
|
Typing @kbd{a} will apply the current commit to your working tree and
|
|
staging area. This is useful when you are browsing the history of
|
|
some other branch and you want to `cherry-pick' some changes from it
|
|
for your current branch. A typical situation is applying selected bug
|
|
fixes from the development version of a program to a release branch.
|
|
|
|
Typing @kbd{v} will revert the current commit. Thus, it will apply
|
|
the changes made by that commit in reverse. This is obviously useful
|
|
to cleanly undo changes that turned out to be wrong.
|
|
|
|
Typing @kbd{=} will show the differences from the current commit to
|
|
the @dfn{marked} commit.
|
|
|
|
You can mark the current commit by typing @kbd{.}. Some commands,
|
|
such as @kbd{=}, will use the current commit and the marked commit as
|
|
implicit arguments. Other commands will offer the marked commit as a
|
|
default when prompting for their arguments.
|
|
|
|
@node Diffing
|
|
@chapter Diffing
|
|
|
|
To show the changes from you working tree to another revision, type
|
|
@kbd{d}. To show the changes between two arbitrary revisions, type
|
|
@kbd{D}.
|
|
|
|
@node Resetting
|
|
@chapter Resetting
|
|
|
|
Once you have added a commit to your local repository, you can not
|
|
change that commit anymore in any way. But you can reset your current
|
|
head to an earlier commit and start over.
|
|
|
|
If you have published your history already, rewriting it in this way
|
|
can be confusing and should be avoided. However, rewriting your local
|
|
history is fine and it is often cleaner to fix mistakes this way than
|
|
by reverting commits (with @kbd{R}, for example).
|
|
|
|
Typing @kbd{x} will ask for a revision and reset your current head to
|
|
it. No changes will be made to your working tree and staging area.
|
|
Thus, the @emph{Staged changes} section in the status buffer will show
|
|
the changes that you have removed from your commit history. You can
|
|
commit the changes again as if you had just made them, thus rewriting
|
|
history.
|
|
|
|
Typing @kbd{x} while point is in a line that describes a commit will
|
|
offer this commit as the default revision to reset to. Thus, you can
|
|
move point to one of the commits in the @emph{Unpushed commits}
|
|
section and hit @kbd{x RET} to reset your current head to it.
|
|
|
|
Type @kbd{X} to reset your working tree and staging area to the most
|
|
recently committed state. This will discard your local modifications,
|
|
so be careful.
|
|
|
|
@node Branching
|
|
@chapter Branching
|
|
|
|
The current branch is indicated in the header of the status buffer.
|
|
You can switch to a different branch by typing @kbd{b}. This will
|
|
immediately checkout the branch into your working copy, so you
|
|
shouldn't have any local modifications when switching branches.
|
|
|
|
Similar to @kbd{x}, typing @kbd{b} while point is at a commit
|
|
description will offer that commit as the default to switch to.
|
|
This will result in a detached head.
|
|
|
|
To create a new branch and switch to it immediately, type @kbd{B}.
|
|
|
|
@node Merging
|
|
@chapter Merging
|
|
|
|
Magit offers two ways to merge branches: manually and automatic. A
|
|
manual merge will apply all changes to your working tree and staging
|
|
area, but will not commit them, while a automatic merge will go ahead
|
|
and commit them immediately.
|
|
|
|
Type @kbd{m} to initiate a manual merge, and type @kbd{M} for a
|
|
automatic merge.
|
|
|
|
A manual merge is useful when carefully merging a new feature that you
|
|
want to review and test before even committing it. A automatic merge
|
|
is appropriate when you are on a feature branch and want to catch up
|
|
with the master, say.
|
|
|
|
After initiating a manual merge, the header of the status buffer will
|
|
remind you that the next commit will be a merge commit (with more than
|
|
one parent). If you want to abort a manual merge, just do a hard
|
|
reset to HEAD.
|
|
|
|
Merges can fail if the two branches you merge want to introduce
|
|
conflicting changes. In that case, the automatic merge stops before
|
|
the commit, essentially falling back to a manual merge. You need to
|
|
resolve the conflicts and stage the resolved files, for example with
|
|
@kbd{S}.
|
|
|
|
You can not stage individual hunks one by one as you resolve them, you
|
|
can only stage whole files once all conflicts in them have been
|
|
resolved.
|
|
|
|
@node Rebasing
|
|
@chapter Rebasing
|
|
|
|
Typing @kbd{R} in the status buffer will initiate a rebase or, if one
|
|
is already in progress, ask you how to continue.
|
|
|
|
When a rebase is stopped in the middle because of a conflict, the
|
|
header of the status buffer will indicate how far along you are in the
|
|
series of commits that are being replayed.
|
|
|
|
Of course, you can initiate a rebase in any number of ways, by
|
|
configuring @code{git pull} to rebase instead of merge, for example.
|
|
Such a rebase can be finished with @kbd{R} as well.
|
|
|
|
@node Pushing and Pulling
|
|
@chapter Pushing and Pulling
|
|
|
|
Magit will run @code{git push} when you type @kbd{P}. You can type
|
|
@kbd{$} to pop up a buffer with the transcript of running these
|
|
commands.
|
|
|
|
Typing @kbd{f} will run @code{git remote update} and @kbd{F} will run
|
|
@code{git pull}.
|
|
|
|
That's almost all the support for remote repositories that Magit
|
|
offers. You should have setup your Git configuration to do the right
|
|
thing for @code{git push} and @code{git pull}.
|
|
|
|
If you have configured a default remote repository for the current
|
|
branch (by setting the Git config option
|
|
@code{branch.<branch>.remote}), Magit will show that repository in the
|
|
status buffer header.
|
|
|
|
In this case, the status buffer will also have a @emph{Unpushed
|
|
commits} section that shows the commits on your current head that are
|
|
not in the branch named @code{<remote>/<branch>}. This section works
|
|
just like the history buffer: you can see details about a commit with
|
|
@kbd{RET}, and compare two of them with @kbd{.} and @kbd{=}, and you
|
|
can reset your current head to one of them with @kbd{x}, for example.
|
|
|
|
@bye
|