Manual improvements and updates.
This commit is contained in:
parent
72819bd451
commit
6538ce4e4a
1 changed files with 69 additions and 51 deletions
120
magit.texi
120
magit.texi
|
@ -57,12 +57,17 @@ 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
|
it is probably a good idea to bind @code{magit-status} to a key of
|
||||||
your choice.
|
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 Status
|
@node Status
|
||||||
@chapter Status
|
@chapter Status
|
||||||
|
|
||||||
Running @kbd{M-x magit-status} displays the main interface of Magit,
|
Running @kbd{M-x magit-status} displays the main interface of Magit,
|
||||||
the status buffer. Almost all operations are initiated with single
|
the status buffer.
|
||||||
letter keystrokes from that buffer.
|
|
||||||
|
|
||||||
You can have multiple status buffers active at the same time, each
|
You can have multiple status buffers active at the same time, each
|
||||||
associated with its own Git repository. Running @code{magit-status}
|
associated with its own Git repository. Running @code{magit-status}
|
||||||
|
@ -124,9 +129,9 @@ 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
|
description. Once you are happy with the description, type @kbd{C-c
|
||||||
C-c} in that buffer to commit the staged changes.
|
C-c} in that buffer to commit the staged changes.
|
||||||
|
|
||||||
Typing @kbd{C} will also pop up the change description buffer, but it
|
Typing @kbd{C} will also pop up the change description buffer, but in
|
||||||
will also try to insert a ChangeLog-style entry for the change that
|
addition, it will try to insert a ChangeLog-style entry for the change
|
||||||
point is in.
|
that point is in.
|
||||||
|
|
||||||
If the current branch is associated with a remote repository, the
|
If the current branch is associated with a remote repository, the
|
||||||
status buffer will show a fourth section, named @emph{Unpushed
|
status buffer will show a fourth section, named @emph{Unpushed
|
||||||
|
@ -137,39 +142,46 @@ Pulling} for more information.
|
||||||
@node History
|
@node History
|
||||||
@chapter History
|
@chapter History
|
||||||
|
|
||||||
To browse the repository history, type @kbd{l} or @kbd{L} in the
|
To show the repository history of your current head, type @kbd{l}. A
|
||||||
status buffer. Typing @kbd{l} will show the history starting from the
|
new buffer will be shown that displays the history in a terse form.
|
||||||
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
|
The first paragraph of each commit message is displayed, next to a
|
||||||
representation of the relationships between commits.
|
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
|
You can move point to a commit and then cause various things to happen
|
||||||
with it.
|
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
|
Typing @kbd{RET} will pop up more information about the current
|
||||||
commit.
|
commit.
|
||||||
|
|
||||||
Typing @kbd{v} will revert the current commit in your working tree and
|
Typing @kbd{a} will apply the current commit to your working tree and
|
||||||
staging area. Thus, it will apply the changes made by that commit in
|
staging area. This is useful when you are browsing the history of
|
||||||
reverse. This is obviously useful to cleanly undo changes that turned
|
some other branch and you want to `cherry-pick' some changes from it
|
||||||
out to be wrong.
|
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{a} will apply the current commit in the normal way. This
|
Typing @kbd{v} will revert the current commit. Thus, it will apply
|
||||||
is useful when you are browsing the history of some other branch and
|
the changes made by that commit in reverse. This is obviously useful
|
||||||
you want to `cherry-pick' some changes from it for your current
|
to cleanly undo changes that turned out to be wrong.
|
||||||
branch. A typical situation is applying selected bug fixes from the
|
|
||||||
development version of a program to a release branch.
|
|
||||||
|
|
||||||
Typing @kbd{H} will switch your working tree to the current commit.
|
Typing @kbd{=} will show the differences from the current commit to
|
||||||
|
the @dfn{marked} commit.
|
||||||
|
|
||||||
You can also mark the current commit by typing @kbd{.}. Once you have
|
You can mark the current commit by typing @kbd{.}. Some commands,
|
||||||
marked a commit, you can show the differences between it and the
|
such as @kbd{=}, will use the current commit and the marked commit as
|
||||||
current commit by typing @kbd{=}.
|
implicit arguments. Other commands will offer the marked commit as a
|
||||||
|
default when prompting for their arguments.
|
||||||
|
|
||||||
Finally, typing @kbd{^} will use the current commit as the new
|
@node Diffing
|
||||||
starting point of the history buffer.
|
@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
|
@node Resetting
|
||||||
@chapter Resetting
|
@chapter Resetting
|
||||||
|
@ -178,37 +190,43 @@ 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
|
change that commit anymore in any way. But you can reset your current
|
||||||
head to an earlier commit and start over.
|
head to an earlier commit and start over.
|
||||||
|
|
||||||
If you have published your history already, rewriting history in this
|
If you have published your history already, rewriting it in this way
|
||||||
way can be confusing and should be avoided. However, rewriting your
|
can be confusing and should be avoided. However, rewriting your local
|
||||||
local history is fine and it is often cleaner to fix mistakes this way
|
history is fine and it is often cleaner to fix mistakes this way than
|
||||||
than by reverting commits (with @kbd{R} in the history buffer, for
|
by reverting commits (with @kbd{R}, for example).
|
||||||
example).
|
|
||||||
|
|
||||||
Magit gives you two ways to reset your current head: soft and hard.
|
Typing @kbd{x} will ask for a revision and reset your current head to
|
||||||
Type @kbd{x} to do a soft reset. This will change the current head to
|
it. No changes will be made to your working tree and staging area.
|
||||||
the commit that you specify, but your current working tree and staging
|
Thus, the @emph{Staged changes} section in the status buffer will show
|
||||||
area will not be touched. This is useful to redoing the last commit
|
the changes that you have removed from your commit history. You can
|
||||||
to correct the commit message, for example.
|
commit the changes again as if you had just made them, thus rewriting
|
||||||
|
history.
|
||||||
|
|
||||||
Type @kbd{X} to do a hard reset. This will reset the current head to
|
Typing @kbd{x} while point is in a line that describes a commit will
|
||||||
the commit you specify and will check it out so that your working tree
|
offer this commit as the default revision to reset to. Thus, you can
|
||||||
and staging area will match it. In other words, a hard reset will
|
move point to one of the commits in the @emph{Unpushed commits}
|
||||||
throw away the history completely, which can be useful to abort
|
section and hit @kbd{x RET} to reset your current head to it.
|
||||||
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
|
Type @kbd{X} to reset your working tree and staging area to the most
|
||||||
current head, but it will reset your working tree and staging area
|
recently committed state. This will discard your local modifications,
|
||||||
back to the last committed state.
|
so be careful.
|
||||||
|
|
||||||
@node Branching and Merging
|
@node Branching and Merging
|
||||||
@chapter Branching and Merging
|
@chapter Branching and Merging
|
||||||
|
|
||||||
The current branch is indicated in the header of the status buffer.
|
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
|
You can switch to a different branch by typing @kbd{b}. This will
|
||||||
new branch and check it out immediately, type @kbd{B}.
|
immediately checkout the branch into your working copy, so you
|
||||||
|
shouldn't have any local modifications when switching branches.
|
||||||
|
|
||||||
You can also compare your working tree with some other branch. Type
|
Similar to @kbs{x}, typing @kbd{b} while point is at a commit
|
||||||
@kbd{d} and then specify the branch to compare with.
|
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
|
Magit offers two ways to merge branches: manually and automatic. A
|
||||||
manual merge will apply all changes to your working tree and staging
|
manual merge will apply all changes to your working tree and staging
|
||||||
|
@ -219,9 +237,9 @@ Type @kbd{m} to initiate a manual merge, and type @kbd{M} for a
|
||||||
automatic merge.
|
automatic merge.
|
||||||
|
|
||||||
A manual merge is useful when carefully merging a new feature that you
|
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
|
want to review and test before even committing it. A automatic merge
|
||||||
appropriate when you are on a feature branch and want to catch up with
|
is appropriate when you are on a feature branch and want to catch up
|
||||||
the master, say.
|
with the master, say.
|
||||||
|
|
||||||
After initiating a manual merge, the header of the status buffer will
|
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
|
remind you that the next commit will be a merge commit (with more than
|
||||||
|
|
Loading…
Reference in a new issue