276 lines
11 KiB
Text
276 lines
11 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::
|
|
* Status::
|
|
* History::
|
|
* Resetting::
|
|
* Branching and 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.
|
|
|
|
@node Status
|
|
@chapter Status
|
|
|
|
Running @kbd{M-x magit-status} displays the main interface of Magit,
|
|
the status buffer. Almost all operations are initiated with single
|
|
letter keystrokes from that 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 three or four sections that show
|
|
details about the working tree and the staging area.
|
|
|
|
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}.
|
|
|
|
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 it
|
|
will also 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 browse the repository history, type @kbd{l} or @kbd{L} in the
|
|
status buffer. Typing @kbd{l} will show the history starting from the
|
|
current head, while @kbd{L} will ask for a starting point.
|
|
|
|
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.
|
|
|
|
You can move point to a commit and then cause various things to happen
|
|
with it.
|
|
|
|
Typing @kbd{RET} will pop up more information about the current
|
|
commit and typing @kbd{l} will use it as the new starting point of the
|
|
history buffer.
|
|
|
|
Typing @kbd{R} will revert the current commit in your working tree and
|
|
staging area. 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{P} will apply the current commit in the normal way. 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{C} will switch your working tree to the current commit.
|
|
|
|
You can also mark the current commit by typing @kbd{.}. Once you have
|
|
marked a commit, you can show the differences between it and the
|
|
current commit by typing @kbd{=}.
|
|
|
|
@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 history 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} in the history buffer, for
|
|
example).
|
|
|
|
Magit gives you two ways to reset your current head: soft and hard.
|
|
Type @kbd{x} to do a soft reset. This will change the current head to
|
|
the commit that you specify, but your current working tree and staging
|
|
area will not be touched. This is useful to redoing the last commit
|
|
to correct the commit message, for example.
|
|
|
|
Type @kbd{X} to do a hard reset. This will reset the current head to
|
|
the commit you specify and will check it out so that your working tree
|
|
and staging area will match it. In other words, a hard reset will
|
|
throw away the history completely, which can be useful to abort
|
|
experimental changes (like merging a branch just to see what happens).
|
|
|
|
In particular, doing a hard reset to HEAD will have no effect on the
|
|
current head, but it will reset your working tree and staging area
|
|
back to the last committed state.
|
|
|
|
@node Branching and Merging
|
|
@chapter Branching and Merging
|
|
|
|
The current branch is indicated in the header of the status buffer.
|
|
You can check out a different branch by typing @kbd{b}. To create a
|
|
new branch and check it out immediately, type @kbd{B}.
|
|
|
|
You can also compare your working tree with some other branch. Type
|
|
@kbd{d} and then specify the branch to compare with.
|
|
|
|
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 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 pull} when you type @kbd{U} in the status
|
|
buffer, and it will run @code{git push} when you type @kbd{P}. You
|
|
can type @kbd{p} to pop up a buffer with the transcript of running
|
|
these commands.
|
|
|
|
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 you current head that are
|
|
not in the branch named @code{<remote>/<branch>}. This section works
|
|
much like the history buffer: you can see details about a commit with
|
|
@kbd{RET}, and compare two of them with @kbd{.} and @kbd{=}.
|
|
|
|
@bye
|