[Fix #96] Add documentation for git

modules/git/README.md

@@ -0,0 +1,298 @@
+Git
+===
+
+Enhances the [Git][1] distributed version control system by providing aliases, functions and by exposing repository status information to prompts.
+
+Git **1.7.2** is the [minimum required version][7].
+
+Settings
+--------
+
+### Log
+
+The format of the [git-log][8] output is configurable via the following styles,
+which will be passed to the `--prety=format:` switch.
+
+    zstyle ':prezto:module:git:log:brief' format ''
+    zstyle ':prezto:module:git:log:oneline' format ''
+    zstyle ':prezto:module:git:log:medium' format ''
+
+### Status
+
+Retrieving the status of a repository with submodules can take a long time.
+Submodules may be ignored when they are *dirty*, *untracked*, *all*, or *none*.
+
+    zstyle ':prezto:module:git:status:ignore' submodules 'all'
+
+This setting affects all aliases and functions that call `git-status`.
+
+Aliases
+-------
+
+### Git
+
+  - `g` is short for `git`.
+
+### Branch
+
+  - `gb` lists, creates, renames, and deletes branches.
+  - `gbc` creates a new branch.
+  - `gbl` lists branches and their commits.
+  - `gbL` lists local and remote branches and their commits.
+  - `gbs` lists branches and their commits with ancestery graphs.
+  - `gbS` lists local and remote branches and their commits with ancestery
+    graphs.
+  - `gbx` deletes a branch.
+  - `gbX` deletes a branch irrespective of its merged status.
+  - `gbm` renames a branch.
+  - `gbM` renames a branch even if the new branch name already exists.
+
+
+### Commit
+
+  - `gc` records changes to the repository.
+  - `gca` stages all modified and deleted files.
+  - `gcm` records changes to the repository with the given message.
+  - `gco` checks out a branch or paths to work tree.
+  - `gcO` checks out paths to work tree using the *HEAD* commit.
+  - `gcf` amends the tip of the current branch using the same log message as
+    *HEAD*.
+  - `gcp` applies changes introduced by existing commits.
+  - `gcP` applies changes introduced by existing commits without committing.
+  - `gcr` reverts existing commits by reverting patches and recording new
+     commits.
+  - `gcR` removes the *HEAD* commit.
+  - `gcs` displays various types of objects.
+  - `gcl` displays lost commits.
+
+### Data
+
+  - `gd` displays information about files in the index and the work tree.
+  - `gdc` lists cached files.
+  - `gdx` lists deleted files.
+  - `gdm` lists modified files.
+  - `gdu` lists untracked files.
+  - `gdk` lists killed files.
+  - `gdi` lists ignored files.
+
+### Fetch
+
+  - `gf` downloads objects and references from another repository.
+  - `gfc` clones a repository into a new directory.
+  - `gfm` fetches from and merges with another repository or local branch.
+  - `gfr` fetches from and rebases on another repository or local branch.
+
+### Grep
+
+  - `gg` displays lines matching a pattern.
+  - `ggi` displays lines matching a pattern ignoring case.
+  - `ggl` displays files matching a pattern.
+  - `ggL` displays files are not matching a pattern.
+  - `ggv` displays lines not matching a pattern.
+  - `ggw` displays lines matching a pattern at word boundary.
+
+### Index
+
+  - `gia` adds file contents to the index.
+  - `giA` adds file contents to the index interactively.
+  - `giu` adds file contents to the index (updates only known files).
+  - `gid` displays changes between the index and a named commit (diff).
+  - `giD` displays changes between the index and a named commit (word diff).
+  - `gir` resets current HEAD to the specified state.
+  - `giR` resets current index to the specified state.
+  - `gix` removes files/directories from the index (recursively).
+  - `giX` removes files/directories from the index (recursively and forced).
+
+### Conflict
+
+  - `gCl` lists unmerged files.
+  - `gCa` adds unmerged file contents to the index.
+  - `gCe` executes merge-tool on all unmerged file.
+  - `gCo` checks out our changes for unmerged paths.
+  - `gCO` checks out our changes for all unmerged paths.
+  - `gCt` checks out their changes for unmerged paths.
+  - `gCT` checks out their changes for all unmerged paths.
+
+### Log
+
+  - `gl` displays the log.
+  - `gls` displays the stats log.
+  - `gld` displays the diff log.
+  - `glo` displays the one line log.
+  - `glg` displays the graph log.
+  - `glb` displays the brief commit log.
+  - `glc` displays the commit count for each contributor in descending order.
+
+### Merge
+
+  - `gm` joins two or more development histories together.
+  - `gmC` joins two or more development histories together but does not commit.
+  - `gmF` joins two or more development histories together but does not commit
+     generating a merge commit even if the merge resolved as a fast-forward.
+  - `gma` aborts the conflict resolution, and reconstructs the pre-merge state.
+  - `gmt` runs the merge conflict resolution tools to resolve conflicts.
+
+### Push
+
+  - `gp` updates remote refs along with associated objects.
+  - `gpf` forcefully updates remote refs along with associated objects.
+  - `gpa` updates remote branches along with associated objects.
+  - `gpA` updates remote branches and tags along with associated objects.
+  - `gpt` updates remote tags along with associated objects.
+  - `gpc` updates remote refs along with associated objects and adds *origin*
+     as an upstream reference for the current branch.
+  - `gpp` pulls and pushes from origin to origin.
+
+### Rebase
+
+  - `gr` forward-ports local commits to the updated upstream head.
+  - `gra` aborts the rebase.
+  - `grc` continues the rebase after merge conflicts are resolved.
+  - `gri` makes a list of commits to be rebased and opens the editor.
+  - `grs` skips the current patch.
+
+### Remote
+
+  - `gR` manages tracked repositories.
+  - `gRl` displays remote names and URLs.
+  - `gRa` adds a new remote.
+  - `gRx` removes a remote.
+  - `gRm` renames a remote.
+  - `gRu` fetches remotes updates.
+  - `gRc` deletes all stale remote tracking branches.
+  - `gRs` displays information about a given remote.
+  - `gRb` opens a remote on [GitHub][3] in the default browser.
+
+### Stash
+
+  - `gs` stashes the changes of the dirty working directory.
+  - `gsa` applies the changes recorded in a stash to the working directory.
+  - `gsx` drops a stashed state.
+  - `gsX` drops all the stashed states.
+  - `gsd` lists dropped stashed states.
+  - `gsl` lists stashed states.
+  - `gsL` displays the changes recorded in the stash as a diff between the
+    stashed state and its original parent.
+  - `gsp` removes and applies a single stashed state from the stash list.
+  - `gsr` recovers a given stashed state.
+  - `gss` stashes the changes of the dirty working directory, including untracked.
+  - `gsS` stashes the changes of the dirty working directory interactively.
+  - `gsw` stashes the changes of the dirty working directory retaining the index.
+
+### Submodule
+
+  - `gS` initializes, updates, or inspects submodules.
+  - `gSa` adds given a repository as a submodule.
+  - `gSf` evaluates a shell command in each of checked out submodules.
+  - `gSi` initializes submodules.
+  - `gSI` initializes and clones submodules recursively.
+  - `gSl` lists the commits of all submodules.
+  - `gSm` moves a submodule.
+  - `gSs` synchronizes submodules' remote URL to the value specified in
+    .gitmodules.
+  - `gSu` fetches and merges the latest changes for all submodule.
+  - `gSx` removes a submodule.
+
+### Working directory
+
+  - `gws` displays working-tree status in the short format.
+  - `gwS` displays working-tree status.
+  - `gwd` displays changes between the working tree and the index (diff).
+  - `gwD` displays changes between the working tree and the index (word diff).
+  - `gwr` resets the current HEAD to the specified state, does not touch the
+     index nor the working tree.
+  - `gwR` resets the current HEAD, index and working tree to the specified state.
+  - `gwc` removes untracked files from the working tree (dry-run).
+  - `gwC` removes untracked files from the working tree.
+  - `gwx` removes files from the working tree and from the index recursively.
+  - `gwX` removes files from the working tree and from the index recursively and
+    forcefully.
+
+### Shadows
+
+The following aliases may shadow system commands:
+
+  - `gpt` shadows the [GUID partition table maintenance utility][4].
+  - `gs` shadows the [Ghostscript][5].
+
+If you frequently use the above commands, you may wish to remove said aliases
+from this module or to disable them at the bottom of the zshrc with `unalias`.
+
+You can temporarily bypass an alias by prefixing it with a backward slash:
+`\gpt`.
+
+Functions
+---------
+
+  - `git-branch-current` displays the current branch.
+  - `git-commit-lost` lists lost commits.
+  - `git-dir` displays the path to the Git directory.
+  - `git-hub-browse` opens the [GitHub][3] repository in the default browser.
+  - `git-hub-shorten-url` shortens GitHub URLs.
+  - `git-info` exposes repository information via the `$git_info` associative
+    array.
+  - `git-root` displays the path to the working tree root.
+  - `git-stash-clear-interactive` asks for confirmation before clearing the stash.
+  - `git-stash-dropped` lists dropped stashed states.
+  - `git-stash-recover` recovers given dropped stashed states.
+  - `git-submodule-move` moves a submodule.
+  - `git-submodule-remove` removes a submodule.
+
+Theming
+-------
+
+To display information about the current repository in a prompt, define the
+following styles in the `prompt_name_setup` function.
+
+| Name      | Format Code | Content
+| --------- | :---------: | ---------------------------------------------------
+| action    |     %s      | Special action name
+| added     |     %a      | Added files count
+| ahead     |     %A      | Commits ahead of remote count
+| behind    |     %B      | Commits behind of remote count
+| branch    |     %b      | Branch name
+| commit    |     %c      | Commit hash
+| clean     |     %C      | Clean state
+| deleted   |     %d      | Deleted files count
+| dirty     |     %D      | Dirty files count
+| modified  |     %m      | Modified files count
+| position  |     %p      | Commits from the nearest tag count
+| remote    |     %R      | Remote name
+| renamed   |     %r      | Renamed files count
+| stashed   |     %S      | Stashed states count
+| unmerged  |     %U      | Unmerged files count
+| untracked |     %u      | Untracked files count
+
+First, format the repository state attributes. For example, to format the branch
+and remote names, define the following styles.
+
+    zstyle ':prezto:module:git:info:branch' format 'branch:%b'
+    zstyle ':prezto:module:git:info:remote' format 'remote:%R'
+
+Second, format how the above attributes are displayed in prompts.
+
+    zstyle ':prezto:module:git:info:keys' format \
+      'prompt'  ' git(%b)' \
+      'rprompt' '[%R]'
+
+Last, add `$git_info[prompt]` to `$PROMPT` and `$git_info[prompt]` to
+`$RPROMPT` respectively and call `git-info` in the `prompt_name_preexec` hook
+function.
+
+Authors
+-------
+
+*The authors of this module should be contacted via the [issue tracker][6].*
+
+  - [Sorin Ionescu](https://github.com/sorin-ionescu)
+  - [Colin Hebert](https://github.com/ColinHebert)
+
+[1]: http://www.git-scm.com
+[2]: https://github.com/defunkt/hub
+[3]: https://www.github.com
+[4]: http://www.manpagez.com/man/8/gpt/
+[5]: http://linux.die.net/man/1/gs
+[6]: https://github.com/sorin-ionescu/prezto/issues
+[7]: https://github.com/sorin-ionescu/prezto/issues/219
+[8]: http://www.kernel.org/pub/software/scm/git/docs/git-log.html
+

modules/git/functions/git-dir

@@ -1,5 +1,5 @@
 #
-# Gets the path to the Git directory.
+# Displays the path to the Git directory.
 #
 # Authors:
 #   Sorin Ionescu <sorin.ionescu@gmail.com>

modules/git/functions/git-info

@@ -4,65 +4,6 @@
 # Authors:
 #   Sorin Ionescu <sorin.ionescu@gmail.com>
 #
-# Usage:
-#   Define the following styles in a prompt theme setup function.
-#
-#     # %s - Special action name (am, merge, rebase).
-#     zstyle ':prezto:module:git' action 'action:%s'
-#
-#     # %a - Indicator to notify of added files.
-#     zstyle ':prezto:module:git' added 'added:%a'
-#
-#     # %A - Indicator to notify of ahead branch.
-#     zstyle ':prezto:module:git' ahead 'ahead:%A'
-#
-#     # %B - Indicator to notify of behind branch.
-#     zstyle ':prezto:module:git' behind 'behind:%B'
-#
-#     # %b - Branch name.
-#     zstyle ':prezto:module:git' branch 'branch:%b'
-#
-#     # %C - Indicator to notify of a clean working directory.
-#     zstyle ':prezto:module:git' clean 'clean'
-#
-#     # %c - SHA-1 hash.
-#     zstyle ':prezto:module:git' commit 'commit:%c'
-#
-#     # %d - Indicator to notify of deleted files.
-#     zstyle ':prezto:module:git' deleted 'deleted:%d'
-#
-#     # %D - Indicator to notify of dirty files.
-#     zstyle ':prezto:module:git' dirty 'dirty:%D'
-#
-#     # %m - Indicator to notify of modified files.
-#     zstyle ':prezto:module:git' modified 'modified:%m'
-#
-#     # %p - HEAD position in relation to the nearest branch, remote, tag.
-#     zstyle ':prezto:module:git' position 'position:%p'
-#
-#     # %R - Remote name.
-#     zstyle ':prezto:moduleit' remote 'remote:%R'
-#
-#     # %r - Indicator to notify of renamed files.
-#     zstyle ':prezto:module:git' renamed 'renamed:%r'
-#
-#     # %S - Indicator to notify of stashed files.
-#     zstyle ':prezto:module:git' stashed 'stashed:%S'
-#
-#     # %U - Indicator to notify of unmerged files.
-#     zstyle ':prezto:module:git' unmerged 'unmerged:%U'
-#
-#     # %u - Indicator to notify of untracked files.
-#     zstyle ':prezto:module:git' untracked 'untracked:%u'
-#
-#     # Ignore submodule when it is 'dirty', 'untracked', 'all', or 'none'.
-#     zstyle ':prezto:module:git:ignore' submodule ''
-#
-#     # Prompts.
-#     zstyle ':prezto:module:git' info \
-#       'prompt'  ' git:(%b%C%D)' \
-#       'rprompt' ''
-#
 
 # Gets the Git special action (am, bisect, cherry, merge, rebase).
 # Borrowed from vcs_info and edited.

modules/git/functions/git-root

@@ -1,5 +1,5 @@
 #
-# Displays the Git repository root.
+# Displays the path to the working tree root.
 #
 # Authors:
 #   Sorin Ionescu <sorin.ionescu@gmail.com>