This will eventually become the main (Home) page for Egg.

Egg: Emacs Got Git

Egg is not a git porcelain. It shares the
same goals with git aliases: make common git operations more
convenient to perform.

Egg will not provide binding for many git commands because:

• In the author’s humble opinion, some commands (such as
  git init) are better invoked in a regular shell.
• The author is a git newbie, and don’t know how to use some
  advanced git commands (such as git repack.)
• The author is not familiar with some git commands because they
  were never used by the author.

To use egg, simply compile the egg.el file then load the
egg.elc file. You can put the egg.elc file
somewhere in your emacs load-path and add (require 'egg) in your .emacs file.

Once activated, egg will turn on egg-minor-mode when a
file was opened in a git repository. However, the first thing should
be done after loading the first time is to to customize egg.

Customizations

M-x customize-group egg

Some (possibly) important customizations before using egg:

• egg-git-command : this variable’s default value is
  "git". It must be set to the appropriate incantation if
  git is not in exec-path.
• egg-patch-command : same issue as with egg-git-command.
• egg-git-rebase-subdir : git’s DOTEST directory keep changing from
  one version of git to another. one must set this to the appropriate value for
  the version of git currently used.
• egg-mode-key-prefix : key prefix for the
  egg-minor-mode‘s commands. By default this was set to
  the VC’s prefix C-x v, and thus, C-x v =
  would invoke the command egg-file-diff.
• egg-refresh-index-in-background: if enabled, egg will try
  to refresh the index of the visited repositories when emacs has been
  idle for egg-background-idle-period seconds in order to
  improve git commands’s responsiveness.
• egg-background-idle-period : the Emacs’s idle threshold
  before egg start invoking background jobs.
• egg-confirm-next-action : if disabled, egg will not prompt
  for confirmation in egg-next-action.
• egg-buffer-hide-section-type-on-start : this option let the
  user customize the initial display of the deltas in many egg special
  buffers. E.g. one can use this option to initially only show the
  file-names and hide the details of the files in a delta.

Minor mode key-bindings

When egg-minor-mode is enabled in a file buffer, egg
provides many bindings for common git commands as well as egg specific
commands. The key-prefix shown in the below section assume that
egg-mode-key-prefix is C-x v.

Egg also provides a file-mode menu in the menubar which provides
access to the above commands.

History Annotations/Blame mode

egg-file-toggle-blame-mode

When blame-mode is on, the buffer is marked read-only. Disabling
blame-mode will restore the original read-only mode of the buffer.

Special Buffers

Egg creates various special-buffers for each repositories. Each buffer,
using different UI, provides different functionalities to the users.

• The delta manipulation buffers
  • the status buffer
  • the diff buffer
• The log editing buffers
  • the commit buffer
  • the tag buffer
• The commit browsing buffers
  • the log buffer
  • the file log buffer
  • the reflog buffer
  • the query or pickax buffer
  • The stash buffer

The delta editor

Many special buffers embeds one or multiple diffs, i.e. one more
multiple sequence of file deltas. The local keymap of those text
blocks provide a delta-editor that let user maniuplate those diffs
hunk-by-hunk or file-by-file. E.g.

• If a delta sequence was a diff between the work-dir and the index
  then the delta-editor would let the user moving hunk or file’s
  contents from the work-dir to the index or remove the hunk or the
  entire file delta from the work-dir.
• If a delta sequence was a diff between the index and HEAD, then the
  delta edtor would let the user moving hunk or file contents from the
  index to the work-dir.
• If a delta sequence was a diff between commits then the delta-editor
  is in read-only mode. While it cannot move text in read-only mode,
  the local keymap (implementing the delta editor) provide:
  • a convenient way to nagivate the delta sequence.
  • the ability to hide or show a block of text to help the user
    visualizing the global difference

The delta sequence (diff output) is treated as a hierarchical layout
by the local-keymap:

1. A top-level section (unstaged, unmerged, staged, etc.) contains a
   sequence of file deltas or diffs
2. A file delta (difference between a file in the work-dir and in the
   index) contains a sequence of hunks
3. A hunks is the smallest unit that can be moved or removed by the
   delta editor.

The key-bindings in the delta-editor are context-dependent base on the
position of the cursor in the delta sequence. By example:

The common key bindings in a sequence of deltas

These bindings are available anywhere in a sequence of delta.

The common key bindings in a diff section (staged, unstaged or unmerged)

In addition to the previous bindings, the following bindings are
available anywhere in a diff header.

The key bindings in a staged diff section

In addition to the two previous bindings, the following bindings are
available anywhere in a diff header of a staged changes section.

The key bindings in an unstaged diff section

In addition to the common delta’s bindings and the
diff’s bindings, the following bindings are available anywhere in a
diff header of a unstaged changes section.

The key bindings in an unmerged diff section

In addition to the common delta’s bindings and the
diff’s bindings, the following bindings are available anywhere in a
diff header of a unmerged changes section.

The Status Buffer.

The status buffer is launched via C-x v s keys from a
file-buffer when egg-minor-mode is enabled or via the
s key from most egg special buffers.

The primary usage for the status buffer:

• file-by-file or hunk-by-hunk index manipulation.
  • stage a single unstaged hunk: add a single hunk from the a file to the index
  • remove a single unstaged hunk: remove hunk of delta between the index and the file.
  • unstage a single staged hunk: move a hunk from the index to the file.
  • update the index with the (new) contents of a file.
  • revert the contents of a file to match the index
  • revert the contents of a file in the index to match the contents of the file in HEAD.
• resolve merge
  • locate conflict marks in a file
  • resolve merge using ediff3
• resolve/continue/skip/abort rebase
  • locate conflict marks in a file
  • resolve rebase using ediff3
• stash work-in-progress
• resolve conflict’s in stash applications

Status Buffer Screenshot during rebase

Status Buffer Organization

The status-buffer is organized in a hierarchical layout:

• General section
• Help block
• Unstaged Changes
• File 1
• File 1 Hunk 1
• File 1 Hunk 2
• …
• File 2
• …
• Staged Changes
• File 1
• File 1 Hunk 1
• File 1 Hunk 2
• …
• File…
• Untracked Files
• File 1
• …

Status Buffer’s key-bindings

The common key bindings in the egg status-buffer