From be300dbd80529ffa8c845338148055d09c5e24c5 Mon Sep 17 00:00:00 2001 From: Sorin Ionescu Date: Mon, 1 Oct 2012 22:48:13 -0400 Subject: [PATCH] [Fix #96] Add documentation for git --- modules/git/README.md | 298 +++++++++++++++++++++++++++++++++ modules/git/functions/git-dir | 2 +- modules/git/functions/git-info | 59 ------- modules/git/functions/git-root | 2 +- 4 files changed, 300 insertions(+), 61 deletions(-) create mode 100644 modules/git/README.md diff --git a/modules/git/README.md b/modules/git/README.md new file mode 100644 index 0000000..869aeb9 --- /dev/null +++ b/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 + diff --git a/modules/git/functions/git-dir b/modules/git/functions/git-dir index 79b36d7..2e40e9e 100644 --- a/modules/git/functions/git-dir +++ b/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 diff --git a/modules/git/functions/git-info b/modules/git/functions/git-info index 1f7063e..9c99ad4 100644 --- a/modules/git/functions/git-info +++ b/modules/git/functions/git-info @@ -4,65 +4,6 @@ # Authors: # Sorin Ionescu # -# 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. diff --git a/modules/git/functions/git-root b/modules/git/functions/git-root index 6ba52ef..82b7438 100644 --- a/modules/git/functions/git-root +++ b/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