added magit for emacs (better git handling)

1 files changed, 639 insertions, 0 deletions

diff --git a/emacs.d/lisp/magit/magit.texi b/emacs.d/lisp/magit/magit.texi
new file mode 100644
index 0000000..4930d92
--- /dev/null
+++ b/emacs.d/lisp/magit/magit.texi
@@ -0,0 +1,639 @@
+\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, 2009 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::             
+* Sections::                    
+* Status::                      
+* Untracked files::             
+* Staging and Committing::      
+* History::                     
+* Reflogs::                     
+* Diffing::                     
+* Tagging::                     
+* Resetting::                   
+* Stashing::                    
+* Branching::                   
+* Wazzup::                      
+* Merging::                     
+* Rebasing::                    
+* Rewriting::                   
+* Pushing and Pulling::         
+* Interfacing with Subversion::  
+@end menu
+
+@node Introduction
+@chapter Introduction
+
+With Magit, you can inspect and modify your Git repositories with
+Emacs.  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.  There is support for cherry picking, reverting, merging,
+rebasing, and other common Git operations.
+
+Magit is not a complete interface to Git; it just aims to make the
+most common Git operations convenient.  Thus, Magit will likely 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 in all Magit buffers.
+
+Naturally, Magit runs the @code{git} command to do most of the work.
+The @code{*magit-process*} buffer contains the transcript of the most
+recent command.  You can switch to it with @kbd{$}.
+
+@node Acknowledgments
+@chapter Acknowledgments
+
+From day one of the first Magit announcement, John Wiegley has
+contributed numerous fixes, UI improvements, and new features.
+Thanks!
+
+Linh Dang and Christian Neukirchen also contributed from day one.
+Thanks!
+
+Phil Hagelberg joined a few days later.  Thanks!
+
+Alex Ott contributed support for git svn.  Thanks!
+
+Marcin Bachry contributed bug fixes and support for decorated logs.
+Thanks!
+
+Alexey Voinov fixed bugs.  Thanks!
+
+Rémi Vanicat helped with Tramp support.  Thanks!
+
+@node Sections
+@chapter Sections
+
+All Magit buffers are structured into nested 'sections'.  These
+sections can be hidden and shown individually.  When a section is
+hidden, only its first line is shown and all its children are
+completely invisible.
+
+The most fine-grained way to control the visibility of sections is the
+@kbd{TAB} key.  It will to toggle the current section (the section
+that contains point) between being hidden and being shown.
+
+Typing @kbd{S-TAB} toggles the visibility of the children of the
+current section.  When all of them are shown, they will all be hidden.
+Otherwise, when some or all are hidden, they will all be shown.
+
+The digit keys @kbd{1}, @kbd{2}, @kbd{3}, and @kbd{4} control the
+visibility of sections based on levels.  Hitting @kbd{2}, for example,
+will show sections on levels one and two, and will hide sections on
+level 3.  However, only sections that are a parent or child of the
+current section are affected.
+
+For example, when the current section is on level 3 and you hit
+@kbd{1}, the grand-parent of the current section (which is on level
+one) will be shown, and the parent of the current section (level 2)
+will be hidden.  The visibility of no other section will be changed.
+
+This sounds a bit complicated, but you'll figure it out.
+
+Using @kbd{M-1}, @kbd{M-2}, @kbd{M-3}, and @kbd{M-4} is similar to the
+unmodified digits, but now all sections on the respective level are
+affected, regardless of whether or not they are related to the current
+section.
+
+For example, @kbd{M-1} will only show the first lines of the top-level
+sections and will hide everything else.  Typing @kbd{M-4} on the other
+hand will show everything.
+
+Because of the way the status buffer is set up, some changes to
+section visibility are more common than others.  Files are on level 2
+and diff hunks are on level 4.  Thus, you can type @kbd{2} to collapse
+the diff of the current file, and @kbd{M-2} to collapse all files.
+This returns the status buffer to its default setup and is a quick way
+to unclutter it after drilling down into the modified files.
+
+Because @kbd{2} and @kbd{M-2} are so common in the status buffer, they
+are bound to additional, more mnemonic keys: @kbd{M-h} (hide) and
+@kbd{M-H} (hide all).  Likewise @kbd{4} and @kbd{M-4} are also
+available as @kbd{M-s} (show) and @kbd{M-S} (show all).
+
+In other buffers than the status buffer, @kbd{M-h}, @kbd{M-H},
+@kbd{M-s}, and @kbd{M-S} might work on different levels than on 2 and
+4, but they keep their general meaning: @kbd{M-H} hides all detail,
+and @kbd{M-S} shows everything.
+
+@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.
+
+When invoking @kbd{M-x magit-status} from within a Git repository, it
+will switch to the status buffer of that repository.  Otherwise, it
+will prompt for a directory.  With a prefix argument, it will always
+prompt.
+
+You can set @code{magit-repo-dirs} to customize how
+@code{magit-status} asks for the repository to work on.  When
+@code{magit-repo-dirs} is nil, @code{magit-status} will simply ask for
+a directory.
+
+If you specify a directory that is not a Git repository, @kbd{M-x
+magit-status} will offer to initialize it as one.
+
+When @code{magit-repo-dirs} is not nil, it is treated as a list of
+directory names, and @code{magit-status} will find all Git
+repositories in those directories and offer them for completion.
+(Magit will only look @code{magit-repo-dirs-depth} levels deep,
+however.)
+
+With two prefix arguments, @code{magit-status} will always prompt for
+a raw directory.
+
+Thus, you would normally set @code{magit-repo-dirs} to the places
+where you keep most of your Git repositories and switch between them
+with @kbd{C-u M-x magit-status}.  If you want to go to a repository
+outside of your normal working areas, or if you want to create a new
+repository, you would use @kbd{C-u C-u M-x magit-status}.
+
+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 a number of sections that show details
+about the working tree and the staging area.  You can hide and show
+them as described in the previous section.
+
+The first section shows @emph{Untracked files}, if there are any.  See
+@ref{Untracked files} for more details.
+
+Two section show your local changes.  They are explained fully in the
+next chapter, @ref{Staging and Committing}.
+
+If the current branch is associated with a remote tracking branch, the
+status buffer shows the differences between the current branch and the
+tracking branch.  See @ref{Pushing and Pulling} for more information.
+
+During a history rewriting session, the status buffer shows the
+@emph{Pending changes} and @emph{Pending commits} sections.  See
+@ref{Rewriting} for more details.
+
+@node Untracked files
+@chapter Untracked files
+
+Untracked files are shown in the @emph{Untracked files} section.
+
+You can add a untracked file to the staging area with @kbd{s}.  If
+point is on the @emph{Untracked files} section title when you it
+@kbd{s}, all untracked files are staged.
+
+Typing @kbd{C-u S} anywhere will also stage all untracked files,
+together with all changes to the tracked files.
+
+You can instruct Git to ignore them by typing @kbd{i}.  This will add
+the filename to the @code{.gitignore} file.  Typing @kbd{C-u i} will
+ask you for the name of the file to ignore.  This is useful to ignore
+whole directories, for example.  The @kbd{I} command is similar to
+@kbd{i} but will add the file to @code{.git/info/exclude} instead.
+
+To delete a untracked file forever, use @kbd{k}.  If point is on the
+@emph{Untracked files} section title when you it @kbd{k}, all
+untracked files are deleted.
+
+@node Staging and Committing
+@chapter Staging and Committing
+
+Comitting with Git is a two step process: first you add the changes
+you want to commit to a 'staging area', and then you commit them to
+the repository.  This allows you to only commit a subset of your local
+changes.
+
+Magit allows you to ignore the staging area if you wish.  As long as
+your staging area is unused, Magit will show your uncomitted changes
+in a section named @emph{Changes}.
+
+When the staging area is in use, Magit uses two sections:
+@emph{Unstaged changes} and @emph{Staged changes}.  The @emph{Staged
+changes} section shows the changes that will be included in the next
+commit, while the @emph{Unstaged changes} section shows the changes
+that will be left out.
+
+To move a unstaged hunk 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.
+
+If the region is active when you type @kbd{s} or @kbd{u}, only the
+changes in the region are staged or unstaged.  (This works line by
+line: if the beginning of a line is in the region it is included in
+the changes, otherwise it is not.)
+
+To move all hunks of all diffs into the staging area in one go, type
+@kbd{S}.  To unstage everything, type @kbd{U}.
+
+Typing @kbd{C-u S} will stage all untracked files in addition to the
+changes to tracked files.
+
+You can discard uncommitted changes by moving point into a hunk and
+typing @kbd{k}.  The changes to discard are selected as with @kbd{s}
+and @kbd{u}.
+
+Before committing, you should write a short description of the
+changes.
+
+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 perform the commit.
+
+Typing @kbd{c} when the staging area is unused is a special situation.
+Normally, the next commit would be empty, but you can configure Magit
+to do something more useful by customizing the
+@code{magit-commit-all-when-nothing-staged} variable.  One choice is
+to instruct the subsequent @kbd{C-c C-c} to commit all changes.
+Another choice is stage everything at the time of hitting @kbd{c}.
+
+You can type @kbd{C-c C-a} in the buffer with the change description
+to toggle a flag that determines whether the next commit will
+@emph{amend} the current commit in HEAD.
+
+Typing @kbd{C-c C-s} will toggle the @code{--signoff} option.  The
+default is determined by the @code{magit-commit-signoff} customization
+variable.
+
+If you change your mind and don't want to go ahead with your commit
+while you are in the @code{*magit-log-edit*} buffer, you can just
+switch to another buffer, continue editing there, staging and
+unstaging things until you are happy, and then return to the
+@code{*magit-log-edit*} buffer, maybe via @kbd{C-x b}, or by hitting
+@kbd{c} again in a Magit buffer.
+
+If you want to erase the @code{*magit-log-edit*} buffer and bury it,
+you can hit @kbd{C-c C-k} in it.
+
+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.
+
+@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.
+
+Giving a prefix argument to @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.
+
+Typing @kbd{L} (or @kbd{C-u L}) will show the log in a more verbose
+form.
+
+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
+and move point into the new buffer.  Typing @kbd{SPC} and @kbd{DEL}
+will also show the information, but will scroll the new buffer up or
+down (respectively) when typed again.
+
+Typing @kbd{a} will apply the current commit to your current branch.
+This is useful when you are browsing the history of some other branch
+and you want to `cherry-pick' some changes from it.  A typical
+situation is applying selected bug fixes from the development version
+of a program to a release branch.  The cherry-picked changes will not
+be committed automatically; you need to do that explicitly.
+
+Typing @kbd{A} will cherry-pick the current commit and will also
+commit the changes automatically when there have not been any
+conflicts.
+
+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.  As with @kbd{a},
+you need to commit the changes explicitly.
+
+Typing @kbd{C-w} will copy the sha1 of the current commit into the
+kill ring.
+
+Typing @kbd{=} will show the differences from the current commit to
+the @dfn{marked} commit.
+
+You can mark the current commit by typing @kbd{.}.  When the current
+commit is already marked, typing @kbd{.} will unmark it.  To unmark
+the marked commit no matter where point is, use @kbd{C-u .}.
+
+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 Reflogs
+@chapter Reflogs
+
+You can use @kbd{h} and @kbd{H} to browse your @emph{reflog}, the
+local history of changes made to your repository heads.  Typing
+@kbd{H} will ask for a head, while @kbd{h} will show the reflog of
+@code{HEAD}.
+
+The resulting buffer is just like the buffer produced by @kbd{l} and
+@kbd{L} that shows the commit history.
+
+@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}.
+
+You can use @kbd{a} within the diff output to apply the changes to
+your working tree.  As usual when point is in a diff header for a
+file, all changes for that file are applied, and when it is in a hunk,
+only that hunk is.  When the region is active, the applied changes are
+restricted to that region.
+
+Typing @kbd{v} will apply the selected changes in reverse.
+
+@node Tagging
+@chapter Tagging
+
+Typing @kbd{t} will make a lighweight tag.  Typing @kbd{T} will make a
+annotated tag.  It will put you in the normal @code{*magit-log-edit}
+buffer for writing commit messages, but typing @kbd{C-c C-c} in it
+will make the tag instead.  This is controlled by the @code{Tag} field
+that will be added to the @code{*magit-log-edit*} buffer.  You can
+edit it, if you like.
+
+@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{v}, 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.
+
+You can give a prefix to @kbd{x} if you want to reset both the current
+head and your working tree to a given commit.  This is the same as
+first using an unprefixed @kbd{x} to reset only the head, and then
+using @kbd{X}.
+
+@node Stashing
+@chapter Stashing
+
+You can create a new stash with @kbd{z}.  Your stashes will be listed
+in the status buffer, and you can apply them with @kbd{a} and pop them
+with @kbd{A}.  To drop a stash, use @kbd{k}.
+
+Typing @kbd{Z} will create a stash just like @kbd{z}, but will leave
+the changes in your working tree and index.
+
+You can visit and show stashes in the usual way: Typing @kbd{SPC} and
+@kbd{DEL} will pop up a buffer with the description of the stash and
+scroll it, typing @kbd{RET} will move point into that buffer.
+
+@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.
+
+If you try to switch to a remote branch, Magit will offer to create a
+local tracking branch for it instead.  This way, you can easily start
+working on new branches that have appeared in a remote repository.
+
+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 Wazzup
+@chapter Wazzup
+
+Typing @kbd{w} will show a summary of how your other branches relate
+to the current branch.
+
+For each branch, you will get a section that lists the commits in that
+branch that are not in the current branch.  The sections are initially
+collapsed; you need to explicitly open them with @kbd{TAB} (or
+similar) to show the lists of commits.
+
+When point is on a @emph{N unmerged commits in ...} title, the
+corresponding branch will be offered as the default for a merge.
+
+Hitting @kbd{i} on a branch title will ignore this branch in the
+wazzup view.  You can use @kbd{C-u w} to show all branches, including
+the ignored ones.  Hitting @kbd{i} on an already ignored branch in
+that view will unignore it.
+
+@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 with @kbd{X}.
+
+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 for example with @kbd{e} 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.  When that happens, you
+should resolve the conflicts and stage everything and hit @kbd{R c} to
+continue the rebase.  Alternatively, hitting @kbd{c} or @kbd{C} while
+in the middle of a rebase will also ask you whether to continue the
+rebase.
+
+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 Rewriting
+@chapter Rewriting
+
+As hinted at earlier, you can rewrite your commit history.  For
+example, you can reset he current head to an earlier commit with
+@kbd{x}.  This leaves the working tree unchanged, and the status
+buffer will show all the changes that have been made since that new
+value of the current head.  You can commit these changes again,
+possibly splitting them into multiple commits as you go along.
+
+Amending your last commit is a common special case of rewriting
+history like this.
+
+Another common way to rewrite history is to reset the head to an
+earlier commit, and then to cherry pick the previous commits in a
+different order.  You could pick them from the reflog, for example.
+
+Magit has several commands that can simplify the book keeping
+associated with rewriting.  These commands all start with the @kbd{r}
+prefix key.
+
+Typing @kbd{r s} will start a rewrite operation.  You will be prompted
+for a @emph{base} commit, and all commits between the current head and
+this commit are put in a list of @emph{Pending commits} (including the
+base commit).  The current head will then be reset to the parent of
+the base commit.
+
+You would then typically use @kbd{a} and @kbd{A} to cherry pick
+commits from the list of pending commits in the desired order, until
+all have been applied.  Magit shows which commits have been applied by
+changing their marker from @code{*} to @code{.}.
+
+Using @kbd{A} will immediately commit the commit (as usual).  If you
+want to combine multiple previous commits into a single new one, use
+@kbd{a} to apply them all to your working tree, and then commit them
+together.
+
+Magit has no explicit support for rewriting merge commits.  It will
+happily include merge commits in the list of pending commits, but
+there is no way of replaying them automatically.  You have to redo the
+merge explicitly.
+
+You can also use @kbd{v} to revert a commit when you have changed your
+mind.  This will change the @code{.} mark back to @code{*}.
+
+Once you are done with the rewrite, type @kbd{r t} to remove the book
+keeping information from the status buffer.
+
+If you rather wish to start over, type @kbd{r a}.  This will abort the
+rewriting, resetting the current head back to the value it had before
+the rewrite was started with @kbd{r s}.
+
+Typing @kbd{r f} will @emph{finish} the rewrite: it will apply all
+unused commits one after the other, as if you would us @kbd{A} with
+all of them.
+
+You can change the @kbd{*} and @kbd{.} marks of a pending commit
+explicitly with @kbd{r *} and @kbd{r .}.
+
+In addition to a list of pending commits, the status buffer will show
+the @emph{Pending changes}.  This section shows the diff between the
+original head and the current head.  You can use it to review the
+changes that you still need to rewrite, and you can apply hunks from
+it, like from any other diff.
+
+@node Pushing and Pulling
+@chapter Pushing and Pulling
+
+Magit will run @code{git push} when you type @kbd{P}.  If you give a
+prefix argument to @kbd{P}, you will be prompted for the repository to
+push to.  When no default remote repositor has been configured yet for
+the current branch, you will be prompted as well.  Typing @kbd{P} will
+only push the current branch to the remote.  In other words, it will
+run @code{git push <remote> <branch>}.
+
+Typing @kbd{f} will run @code{git remote update} and @kbd{F} will run
+@code{git pull}.  When you don't have a default branch configured to
+be pulled into the current one, you will be asked for it.
+
+If there is a default remote repository for the current branch, 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}, compare two of them with @kbd{.} and @kbd{=}, and you can
+reset your current head to one of them with @kbd{x}, for example.
+
+When the remote branch has changes that are not in the current branch,
+Magit shows them in a section called @emph{Unpulled changes}.  Typing
+@kbd{F} will merge them into the current branch.
+
+@node Interfacing with Subversion
+@chapter Interfacing with Subversion
+
+Typing @kbd{N r} runs @code{git svn rebase} and typing @kbd{N c} runs
+@code{git svn dcommit}.
+
+@bye