diff options
| -rw-r--r-- | Makefile | 12 | ||||
| -rw-r--r-- | README | 69 | ||||
| -rw-r--r-- | README.md | 508 | ||||
| -rwxr-xr-x | git-precheck | 35 | ||||
| -rw-r--r-- | git-precheck.1 | 67 | ||||
| -rwxr-xr-x | git-sonar | 40 | ||||
| -rw-r--r-- | git-sonar.1 | 498 |
7 files changed, 650 insertions, 579 deletions
@@ -1,4 +1,5 @@ SOURCE=git-sonar git-precheck +MANPAGES=git-sonar.1 git-precheck.1 PREFIX?=/usr/local PWD=$(shell pwd) @@ -16,13 +17,14 @@ all: @echo 'If you want to install *git-sonar* for your user only:' @echo ' PREFIX=$$HOME/.local make install' -install: $(SOURCE) - @echo 'Installing in' $(PREFIX)/bin '...' - mkdir -p $(PREFIX)/bin +install: + @echo 'Installing in' $(PREFIX) '...' + mkdir -p $(PREFIX)/bin $(PREFIX)/share/man/man1 install -m 755 $(SOURCE) $(PREFIX)/bin + install -m 644 $(MANPAGES) $(PREFIX)/share/man/man1 -# Link each file separately since the full PWD is needed -develop: $(SOURCE) +develop: + # Link each file separately since the full PWD is needed @echo 'Symlinking in' $(PREFIX)/bin '...' mkdir -p $(PREFIX)/bin ln -sf $(PWD)/git-sonar $(PREFIX)/bin @@ -0,0 +1,69 @@ + _ _ __ __ + __ _(_) |_ _ / /__ ___ _ __ __ _ _ _\ \ + / _` | | __(_) / __|/ _ \| '_ \ / _` | '__| | + | (_| | | |_ _| \__ \ (_) | | | | (_| | | | | + \__, |_|\__(_) |___/\___/|_| |_|\__,_|_| | | + |___/ \_\ /_/ + +git-sonar is a shell prompt git status indicator, add it to your $PS1 prompt to +see real-time information about the current directory's repository, branch, +changed files, etc. git-sonar is forked from the original project git-radar by +Michael Allen, which is no longer receiving maintenance. +Ref: https://github.com/michaeldfallen/git-radar + +git-sonar also provides git-precheck, a shell utility script which inspects a +repository and returns machine-parseable results not easily gathered from +git status. It is intended for use in other git-related scripts. + + +INSTALLATION +------------ +For a normal installation, run 'make install', but see the output from 'make' +for more installation options. You can run 'git-sonar --version' to confirm +that the install was successful. + + +GETTING STARTED +--------------- +Both of the scripts have an accompanying man-page, which can be viewed after +installation using the 'man' command, or by passing '--help' to either script +directly. + +These are the user-facing documentation and contain more details about usage, +configuration, and inserting git-sonar into your particular shell's prompt. + +Out of the box, git-sonar has a very usable default configuration, and most +features are enabled. One can be up and running by just updating their $PS1 +variable - but see the "USAGE" section of git-sonar's man-page for some possible +$PS1 pitfalls. + + +GETTING SUPPORT +--------------- +Get in touch on the mailing list to ask questions, report problems, submit +patches, or discuss the project! + + git-sonar@normalmode.org + +For more information, or instructions on subscribing, send an email to: + + git-sonar+help@normalmode.org + + +COMPATIBILITY WITH GIT-RADAR +---------------------------- +git-sonar is no longer a "drop in" replacement for git-radar. All of the +environment variables used for configuration have been either renamed, or +removed, and several others have been added. git-sonar does not read from any +special RC files, just the shell environment. Furthermore, both tools support +different command line options. + +git-sonar does preserve the original hallmark features of git-radar, and its +default appearance is very faithful to the original as well. + + +LICENSE +------- +For historical reasons, git-sonar, git-precheck, and associated documentation +are made available under the MIT license - the same license utilized by +git-radar. diff --git a/README.md b/README.md deleted file mode 100644 index c1155d3..0000000 --- a/README.md +++ /dev/null @@ -1,508 +0,0 @@ -# Git Sonar - -A heads up display for git. Fork of 'git-radar' by Michael Allen (https://github.com/michaeldfallen/git-radar). - -![An example of git-sonar] - -Git-sonar is a tool you can add to your prompt to provide at-a-glance -information on your git repo. It's a labour of love I've been dogfooding for the -last few years. Maybe it can help you too. - -**Table of Contents** - -- [Installation](#installation) -- [Usage](#usage) -- [Features](#features) - - [Files status](#files-status) - - [Local commits status](#local-commits-status) - - [Remote commits status](#remote-commits-status) - - [Stash status](#stash-status) - - [(Optional) Auto-fetch repos](#optional-auto-fetch-repos) -- [Customise your prompt](#customise-your-prompt) -- [Support](#support) - - [Ensuring prompt execution](#ensuring-prompt-execution) - - [Configuring colours](#configuring-colours) - - [Exporting Environment Variables](#exporting-environment-variables) - - [Setting an RC file](#setting-an-rc-file) - - [Colour Codes](#colour-codes) - - [Configuration values](#configuration-values) - - [Colouring the Branch part](#colouring-the-branch-part) - - [Colouring the local commits status](#colouring-the-local-commits-status) - - [Colouring the remote commits status](#colouring-the-remote-commits-status) - - [Colouring the file changes status](#colouring-the-file-changes-status) -- [License](#license) -- [Links](#links) - -## Installation - -For a normal installation, run 'make install' (may require sudo), but see the -output from 'make' for more installation options. Run 'git-sonar -h' to confirm -the install is successful. - -## Usage - -To use git-sonar you need to add it to your prompt. This is done in different -ways depending on your shell. - -**Bash** - -Add to your `.bashrc` -```bash -export PS1="$PS1\$(git-sonar) " -``` -[(note: the `\` escaping the `$` is important)](#ensuring-prompt-execution) - -**Zsh** - -Add to your `.zshrc` -```zsh -export PROMPT="$PROMPT\$(git-sonar) " -``` -[(note: the `\` escaping the `$` is important)](#ensuring-prompt-execution) - -**Fish** - -Add to your `config.fish` -```bash -function fish_prompt - set_color $fish_color_cwd - echo -n (prompt_pwd) - echo -n (git-sonar) - set_color normal - echo -n ' > ' -end -``` - -## Features - -### Files status - -The prompt lists the file changes and whether they are staged, unstaged or -untracked. - -Prompt | Meaning ----------------------------|-------- -![git:(master) 3A] | We have 3 untracked files -![git:(master) 2D2M] | We have 2 modifications and 2 deletions not yet staged to commit -![git:(master) 1M1R] | We have 1 modification and a file renamed staged and ready to commit -![git:(master) 1U] | We have a conflict caused by US that we need to address -![git:(master) 1M 1D2M 2A] | A combination of the above types - -Each symbol represents a different change to a file. These are based on what git -considers has happened to the file. - -Symbol | Meaning ---------|-------- -A | A new Added file -D | A file has been Deleted -M | A file has been Modified -R | A file has been renamed -C | A file has been copied -U | A conflict caused by Us -T | A conflict caused by Them -B | A conflict caused by Both us and them - -The color tells you what stage the change is at. - -Color | Meaning ---------|-------- -Green | Staged and ready to be committed (i.e. you have done a `git add`) -Red | Unstaged, you'll need to `git add` them before you can commit -Grey | Untracked, these are new files git is unaware of -Yellow | Conflicted, these need resolved before they can be committed - -The use of feature is controlled by the `GIT_RADAR_FORMAT` environment variable. -See [Customise your prompt](#customise-your-prompt) for how to personalise this. - -### Local commits status - -The prompt will show you the difference in commits between your branch and the -remote your branch is tracking. The examples below assume you are checked out on -`master` and are tracking `origin/master`. - -Prompt | Meaning ---------------------|-------- -![git:(master 2↑)] | We have 2 commits to push up -![git:(master 3↓)] | We have 3 commits to pull down -![git:(master 3⇵5)] | Our version and origins version of `master` have diverged - -The use of feature is controlled by the `GIT_RADAR_FORMAT` environment variable. -See [Customise your prompt](#customise-your-prompt) for how to personalise this. - -### Remote commits status - -The prompt will also show the difference between your branch on origin and what -is on `origin/master`. - -This is the difference between the commits you've pushed up and `origin/master`. - -Prompt | Meaning ----------------------------|--------------- -![git:(m ← 2 my-branch)] | We have 2 commits on `origin/my-branch` that aren't on `origin/master` -![git:(m 4 → my-branch)] | There are 4 commits on `origin/master` that aren't on `origin/my-branch` -![git:(m 1 ⇄ 2 my-branch)] | `origin/master` and `origin/my-branch` have diverged, we'll need to rebase or merge - -The use of feature is controlled by the `GIT_RADAR_FORMAT` environment variable. -See [Customise your prompt](#customise-your-prompt) for how to personalise this. - -### Stash status -The prompt will show you how many stashes you have stored. - -Prompt | Meaning ----------------------------|--------------- -![git:(master) 1≡] | We have one stash - -If you don't rely on this status, you can always hide this part of the prompt by -[customising your prompt](#customise-your-prompt) - -### (Optional) Auto-fetch repos - -Ensuring your refs are up to date I found can be a pain. To streamline this, -git-sonar can be configured to auto-fetch your repo. When the `--fetch` flag is -used git-sonar will run `git fetch` asynchronously every 5 minutes. - -This will only occur when the prompt is rendered and it will only occur on the -repo you are currently in. - -You may also choose to fetch at a customized interval of time. To do so, add -this to your .bashrc, .zshrc: - -```bash -export GIT_RADAR_FETCH_TIME=<seconds> -``` - -For example, to fetch every 30 seconds (instead of the default 5 minutes): - -```bash -export GIT_RADAR_FETCH_TIME=30 -``` - -You can also do this in the gitradarrc file: - -```bash -GIT_RADAR_FETCH_TIME=30 -``` - -## Customise your prompt - -Git Sonar is highly customisable using a prompt format string. The 4 features -above: remote commits, local commits, branch and file changes; are controlled -by the prompt format string. - -Feature | Control string ----------------|--------------- -Remote commits | `%{remote}` -Local commits | `%{local}` -Branch | `%{branch}` -File changes | `%{changes}` -Stashes | `%{stash}` - -You can create any prompt shape you prefer by exporting `GIT_RADAR_FORMAT` with -your preferred shape. The control strings above will be replaced with the output -of the corresponding feature. - -**Examples** - -GIT\_RADAR\_FORMAT | Result ---------------------------------------|--------------------- -`%{branch}%{local}%{changes}` | `master1↑1M` -`[%{branch}] - %{local} - %{changes}` | `[master] - 1↑ - 1M` - -### Prefixing and Suffixing the features - -Often you will want certain parts of the prompt to only appear when there is -content to render. For example, when in a repo you want `[branch]` but when out -of a repo you don't want the `[]` appearing. - -To do this, the control strings support prefixes and suffixes. Prefixes and -Suffixes are separated from the feature name by `:` and will only render if the -feature would render: - -Format: `prompt > %{prefix - :changes: - suffix}` - -In a repo: `prompt > prefix - 1M - suffix` - -Outside a repo: `prompt > ` - -The default prompt format uses this to add spaces only if the feature would -render. In that way the prompt always looks well spaced out no matter how many -features are rendering. - - -## Support - -### Ensuring prompt execution - -When setting your prompt variable, `PROMPT` in Zsh and `PS1` in Bash, it's -important that the function executes each time the prompt renders. That way the -prompt will respond to changes in your git repo. To ensure this you will need -to escape the execution of the function. There are two ways to do this: - -**1. Use `$'` to render raw characters** -```bash -export PROMPT=$'$(git-sonar)' -export PS1=$'$(git-sonar)' -``` - -**2. Use `\` to escape execution of the subshell** -```bash -export PROMPT="\$(git-sonar)" -export PS1="\$(git-sonar)" -``` - -### Configuring colours - -You can configure the colour scheme in two ways: export -[Environment Variables](#exporting-environment-variables) -or use an [rc file](#setting-an-rc-file). - -#### Exporting Environment Variables - -To configure the prompt this way just add to your `~/.bashrc` or `~/.zshrc` an -export directive with the value you want to change. - -**Example: Change the branch colour in Zsh** - -In `~/.zshrc`: -```zsh -export GIT_RADAR_COLOR_BRANCH='$fg[yellow]' -``` - -**Example: Change the branch colour in Bash** - -In `~/.bashrc`: -```zsh -export GIT_RADAR_COLOR_BRANCH='\\033[0;33m' -``` - -#### Setting an RC file - -Git sonar supports multiple rc files. One of these will be sourced when the -prompt renders. - -**Example: Change the branch colour in Zsh** - -In `~/.gitradarrc`: -```zsh -GIT_RADAR_COLOR_BRANCH='$fg[yellow]' -``` - -Create a file at `~/.gitradarrc` which sets the Environment variables listed in -[Configuration values](#configuration-values) using colour codes listed in -[Colour Codes](#Colour-Codes). - - -#### Colour Codes - -Colour codes make use of the colours your terminal app claims to be `red` -or `green`. Using one of these codes will only produce the colour your terminal -claims, so you should customise your colour scheme on your terminal as well as -customising git-sonar. - -Note the "Bright" colours can be shown as bold instead, it depends on your -terminal. By default, for example, the Mac OSX Terminal.app uses the "Bright" -colours to provide 8 new lighter colours but some terminals only support 8 and -will show the text as bold instead. - -Colour | Code for Text | Code for Background ---------------|----------------|-------------------- -Black | `\\033[0;30m` | `\\033[0;40m` -Red | `\\033[0;31m` | `\\033[0;41m` -Green | `\\033[0;32m` | `\\033[0;42m` -Yellow | `\\033[0;33m` | `\\033[0;43m` -Blue | `\\033[0;34m` | `\\033[0;44m` -Magenta | `\\033[0;35m` | `\\033[0;45m` -Cyan | `\\033[0;36m` | `\\033[0;46m` -White | `\\033[0;37m` | `\\033[0;47m` -Bright Black | `\\033[1;30m` | `\\033[1;40m` -Bright Red | `\\033[1;31m` | `\\033[1;41m` -Bright Green | `\\033[1;32m` | `\\033[1;42m` -Bright Yellow | `\\033[1;33m` | `\\033[1;43m` -Bright Blue | `\\033[1;34m` | `\\033[1;44m` -Bright Magenta| `\\033[1;35m` | `\\033[1;45m` -Bright Cyan | `\\033[1;36m` | `\\033[1;46m` -Bright White | `\\033[1;37m` | `\\033[1;47m` -Reset | `\\033[0m` | `\\033[0m` - -Note the Reset will set back to what your terminal claims as standard text and -background. - -#### Configuration values - -All these values should be set using the correct colour code for your -terminal. - -##### Colouring the Branch part - -**GIT_RADAR_COLOR_BRANCH='[colour code]'** -``` -git:(my-branch) - ^^^^^^^^^ -``` -The colour to use for the Branch or git reference. - -It is unset by -`GIT_RADAR_COLOR_BRANCH_RESET` which you can set if you want a different -background colour to return to. - -##### Colouring the local commits status - -**GIT_RADAR_COLOR_LOCAL_AHEAD='[colour code]'** -``` -git:(my-branch 1↑) - ^ -``` -The colour to use for the arrow that indicates how many commits you have to push -up. - -It is unset by `GIT_RADAR_COLOR_LOCAL_RESET` which you can set if you want -a different background colour to return to. - -**GIT_RADAR_COLOR_LOCAL_BEHIND='[colour code]'** -``` -git:(my-branch 1↓) - ^ -``` -The colour to use for the arrow that indicates how many commits you have to pull -down. - -It is unset by `GIT_RADAR_COLOR_LOCAL_RESET` which you can set if you want -a different background colour to return to. - -**GIT_RADAR_COLOR_LOCAL_DIVERGED='[colour code]'** -``` -git:(my-branch 1⇵1) - ^ -``` -The colour to use for the arrow that indicates how many commits your branch has diverged by. - -It is unset by `GIT_RADAR_COLOR_LOCAL_RESET` which you can set if you want -a different background colour to return to. - -##### Colouring the remote commits status - -**GIT_RADAR_COLOR_REMOTE_AHEAD='[colour code]'** -``` -git:(m ← 1 my-branch) - ^ -``` -The colour to use for the arrow that indicates how many commits your branch has to merge on to master. - -It is unset by `GIT_RADAR_COLOR_REMOTE_RESET` which you can set if you want -a different background colour to return to. - -**GIT_RADAR_COLOR_REMOTE_BEHIND='[colour code]'** -``` -git:(m 1 → my-branch) - ^ -``` -The colour to use for the arrow that indicates how many commits your branch is -behind master. - -It is unset by `GIT_RADAR_COLOR_REMOTE_RESET` which you can set if you want -a different background colour to return to. - -**GIT_RADAR_COLOR_REMOTE_DIVERGED='[colour code]'** -``` -git:(m 1 ⇄ 1 my-branch) - ^ -``` -The colour to use for the arrow that indicates how many commits your branch has -diverged from master. - -It is unset by `GIT_RADAR_COLOR_REMOTE_RESET` which you can set if you want -a different background colour to return to. - -**GIT_RADAR_COLOR_REMOTE_NOT_UPSTREAM='[colour code]'** -``` -git:(upstream ⚡ my-branch) - ^ -``` -The colour to use for the lightning bolt which indicates that your branch is not -tracking an upstream branch. - -It is unset by `GIT_RADAR_COLOR_REMOTE_RESET` which you can set if you want -a different background colour to return to. - -##### Colouring the file changes status - -**GIT_RADAR_COLOR_CHANGES_STAGED='[colour code]'** -``` -git:(my-branch) 1M - ^ -``` -The colour to use for the letters that indicate changes that have been staged to -commit. - -It is unset by `GIT_RADAR_COLOR_CHANGES_RESET` which you can set if you want -a different background colour to return to. - -**GIT_RADAR_COLOR_CHANGES_UNSTAGED='[colour code]'** -``` -git:(my-branch) 1M - ^ -``` -The colour to use for the letters that indicate changes that have not yet been -staged to commit. - -It is unset by `GIT_RADAR_COLOR_CHANGES_RESET` which you can set if you want -a different background colour to return to. - -**GIT_RADAR_COLOR_CHANGES_CONFLICTED='[colour code]'** -``` -git:(my-branch) 1B - ^ -``` -The colour to use for the letters that indicate changes that have conflicts that -need resolved. - -It is unset by `GIT_RADAR_COLOR_CHANGES_RESET` which you can set if you want -a different background colour to return to. - -**GIT_RADAR_COLOR_CHANGES_UNTRACKED='[colour code]'** -``` -git:(my-branch) 1A - ^ -``` -The colour to use for the letters that indicate files that are currently not -tracked by git. - -It is unset by `GIT_RADAR_COLOR_CHANGES_RESET` which you can set if you want -a different background colour to return to. - -##### Colouring the stash status - -**GIT_RADAR_COLOR_STASH='[colour code]'** -``` -git:(my-branch) 1≡ - ^ -``` -The colour to use for the lines that indicates how many stashes you have stored. - -It is unset by `GIT_RADAR_COLOR_STASH_RESET` which you can set if you want -a different background colour to return to. - -## License - -Git Radar and Git Sonar are licensed under the MIT license. - -See [LICENSE] for the full license text. - -## Links - -* [mini-git-radar](https://github.com/bogem/mini-git-radar) - lightweight version of git-radar. Only for macOS and bash/fish. - -[LICENSE]: https://github.com/michaeldfallen/git-radar/blob/master/LICENSE -[git:(master) 1≡]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/stash.png -[git:(master) 3A]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/untracked.png -[git:(master) 2D2M]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/unstaged.png -[git:(master) 1M1R]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/added.png -[git:(master) 1U]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/conflicts.png -[git:(master) 1M 1D2M 2A]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/combination.png -[git:(master 2↑)]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/local%20is%20ahead.png -[git:(master 3↓)]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/remote%20is%20behind.png -[git:(master 3⇵5)]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/remote%20local%20diverged.png -[git:(m ← 2 my-branch)]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/branch%20is%20ahead.png -[git:(m 4 → my-branch)]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/master%20is%20ahead.png -[git:(m 1 ⇄ 2 my-branch)]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/master%20branch%20diverged.png -[An example of git-radar]: https://raw.githubusercontent.com/michaeldfallen/git-radar/master/images/detailed.png diff --git a/git-precheck b/git-precheck index fa42eb3..52f1781 100755 --- a/git-precheck +++ b/git-precheck @@ -1,35 +1,6 @@ #!/bin/sh -usage() { - echo "git-precheck [--quiet] [--ignore-dirty] [--ignore-untracked]" - echo "" - echo "If the current working directory is inside a git repository, examine" - echo "the repo for any abnormal state and return an exit code indicating" - echo "the status. If unclean, print a line of text describing each" - echo "condition found." - echo "" - echo " --quiet" - echo " Don't actually print anything." - echo "" - echo " --ignore-dirty" - echo " Don't consider the presence of uncommitted changes to tracked" - echo " files as an abnormal state." - echo "" - echo " --ignore-untracked" - echo " Don't consider the presence of untracked files as an abnormal" - echo " state." - echo "" - echo " Exit codes:" - echo " 0 If inside a repository and all checks return normal" - echo " 1 If untracked files detected" - echo " 2 If dirty/modified files detected" - echo " 3 If any ongoing git operation is in progress" - echo " 4 If not inside a git repository" - echo "" - echo " Exit any other value on error or if 'precheck' operation is" - echo " not completed, such as when viewing this help text." - exit 128 -} +docs() { exec man 1 git-precheck; } quiet="" opt_dirty="true" @@ -40,8 +11,8 @@ while true; do --quiet) quiet="true" ;; --ignore-dirty) opt_dirty="" ;; --ignore-untracked) opt_untracked="" ;; - --help) usage ;; - -h) usage ;; + --help) docs ;; + -h) docs ;; *) break esac shift diff --git a/git-precheck.1 b/git-precheck.1 new file mode 100644 index 0000000..e0861b2 --- /dev/null +++ b/git-precheck.1 @@ -0,0 +1,67 @@ +.TH GIT\-PRECHECK 1 git\-sonar + +.SH NAME +git\-precheck \- detect "unready" state of a git repository + +.SH SYNOPSIS +.B git\-precheck +.RB [ \-\-quiet ] +.RB [ \-\-ignore\-dirty ] +.RB [ \-\-ignore\-untracked ] + +.SH DESCRIPTION +If +.B git\-precheck +is run inside a git repository, it examines the repo for any in\-progress git +operations or unclean state and returns an exit code indicating the status. +Otherwise, +.B git\-precheck +reports that it is not in any git worktree. +.P +If +.B \-\-quiet +is not given, a line of text is printed describing each condition found. + +.SH OPTIONS +.TP +.B \-\-quiet +Don't actually print anything. +.TP +.B \-\-ignore\-dirty +Don't consider the presence of uncommitted changes to tracked files as an +unclean state. +.TP +.B \-\-ignore\-untracked +Don't consider the presence of untracked files as an unclean state. + +.SH EXIT STATUS +.TP +.B 0 +If inside a repository and all checks return normal +.TP +.B 1 +If untracked files are detected +.TP +.B 2 +If dirty/modified files are detected +.TP +.B 3 +If any ongoing git operation is in progress +.TP +.B 4 +If not inside a git repository +.P +.B git\-precheck +will exit with any other value if an error occurs. + +.SH SEE ALSO +.BR git\-sonar (1), +.BR git\-status (1) + +.SH LICENSE +.B git\-precheck +is part of the +.B git\-sonar +project, made available under the terms of the +.B MIT +license. @@ -1,38 +1,8 @@ #!/bin/sh GIT_SONAR_VERSION="v0.9.0-dev" - -usage() { - echo "git-sonar [--fetch] [--no-remote-commits] [--no-local-commits]" - echo " [--no-status] [--no-stash]" - echo "" - echo "git-sonar - a heads up display for git" - echo " $GIT_SONAR_VERSION" - echo "" - echo " --fetch" - echo " Periodically fetch from remote repositories asynchronously in" - echo " the background." - echo "" - echo " --no-remote-commits" - echo " Disable showing commit counts between current upstream branch" - echo " and the project default branch." - echo "" - echo " --no-local-commits" - echo " Disable showing commit counts between the current local and" - echo " upstream branches." - echo "" - echo " --no-status" - echo " Disable showing summary of uncommitted changes. Often faster," - echo " but omits a lot of information." - echo "" - echo " --no-stash" - echo " Disable showing git stash count." - echo "" - echo "git-sonar is intended to be invoked by your shell prompt and may be" - echo "configured through the use of various environment variables. See" - echo "the documentation for more details." - exit 0 -} +version() { exec printf 'git-sonar %s\n' "$GIT_SONAR_VERSION"; } +docs() { exec man 1 git-sonar; } opt_fetch="" opt_remote="true" @@ -47,8 +17,10 @@ while true; do --no-local-commits) opt_local="" ;; --no-status) opt_status="" ;; --no-stash) opt_stash="" ;; - --help) usage ;; - -h) usage ;; + --version) version ;; + -v) version ;; + --help) docs ;; + -h) docs ;; *) break esac shift diff --git a/git-sonar.1 b/git-sonar.1 new file mode 100644 index 0000000..572f815 --- /dev/null +++ b/git-sonar.1 @@ -0,0 +1,498 @@ +.TH GIT\-SONAR 1 git\-sonar + +.SH NAME +git\-sonar \- a heads up display for git + +.SH SYNOPSIS +.B git\-sonar +.RB [ options ] + +.SH DESCRIPTION +git\-sonar is a tool you can add to your shell prompt to provide at\-a\-glance +information about your git repositories. This includes information such as the +name of the checked\-out branch, a summary of the +.B git status +for modified files, the number of commits which may be pushed or pulled, and +more. See the "PROMPT ELEMENTS" section for examples of various possible prompt +outputs. +.P +After installation, git\-sonar is activated by placing a call to the script in +your shell's +.B $PS1 +environment variable (or the equivalent). See the "USAGE" section for +additional instructions on setting up some common shells. +.P +git\-sonar's appearance can be customized by setting various environment +variables. See the "CONFIGURATION" section for an exhaustive list of supported +variables and their descriptions. +.P +As an additional feature, git\-sonar may be configured to periodically and +automatically run +.B git fetch +in the repositories your shell visits. Opt in to this feature by providing +.B \-\-fetch +to the git\-sonar command line. + +.SH USAGE +To use git\-sonar, you need to add it to your shell prompt. This is done in +different ways depending on your shell. +.SS bash +.nf +# Add to .bashrc +PS1="...\\$(git-sonar)..." +.fi +.SS zsh +.nf +# Add to .zshrc +setopt PROMPT_SUBST +export GIT_SONAR_COLOR_PREFIX='%{' +export GIT_SONAR_COLOR_SUFFIX='%}' +PROMPT='...$(git-sonar)...' +.fi +.SS fish +.nf +# Add to config.fish +function fish_prompt + # ... + echo -n (git-sonar) + # ... +end +.fi +.SS Ensuring prompt execution +When setting the prompt variable, it is crucial that git\-sonar executes each +time the prompt renders. This way, the prompt will be able to react to changes +in the repository. Some details of the above snippets are necessary to ensure +this happens: +.P +\- bash requires the use of double\-quotes around the value of +.B $PS1. +.br +\- bash requires escaping the call to +.B git\-sonar +(add the backslash character). +.br +\- zsh requires the use of single\-quotes around the value of +.B $PROMPT, +as well as the use of +.B PROMPT_SUBST. + +.SH PROMPT ELEMENTS +All of the information output by the git\-sonar prompt is implemented by one of +many prompt elements. By default, each one is present in the rendered prompt, +unless it has no information to report. Each element is named in the form of +.B %{element}, +as this is the syntax used by the prompt format customization string (see the +"CONFIGURATION" section for more details). Furthermore, most elements may be +disabled by using a command\-line option (see "OPTIONS"). + +.TP +.B %{branch} +Outputs the name of the checked\-out branch. If +.B HEAD +is detached, outputs the abbreviated commit hash. + +.nf + git:(my-branch) + git:(detached@cb39e58e) +.fi + +.TP +.B %{status} +Outputs a summary of +.B git status \-\-porcelain, +consisting of a count of changed files \- both by change type (addition, +modification, deletion, etc.) as well as stage (changes staged in the index, +unmerged, unstaged, or untracked files). + +Changes from the same stage are grouped together and color\-coded (see +"CONFIGURATION" for setting colors). + +.nf + git:(my-branch) 1\m[green]\fBA\fR\m[] 2\m[red]\fBM\fR\m[]1\m[red]\fBD\fR\m[] 3? + git:(my-branch) 2\m[yellow]\fBU\fR\m[]1\m[yellow]\fBD\fR\m[] +.fi + +The first example shows 1 new file staged for commit, 2 unstaged modifications, +1 unstaged file deletion, as well as 3 untracked files which are unknown to the +repository. + +The second example shows us in the middle of a failed merge, with 2 "both +modified" unmerged files and 1 file "deleted by them/us". + +The change indicators displayed are the same ones used by +.BR git\-status (1) +in the +.B \-\-short +output format. + +.TP +.B %{stash} +If any stashed changes are saved, this element outputs the number of stashes +available with a customizable icon. + +.nf + git:(my-branch) 2\m[yellow]\fB≡\fR\m[] +.fi + +The example shows 2 stashed changes previously saved in this repository. + +.TP +.B %{local} +Outputs the number of commits that are different between +.B HEAD +and the configured upstream branch +.B @{u}, +if present. If there is no upstream branch, or the two are pointing to the +same commit, nothing is output. + +.nf + git:(my-branch \m[green]\fB↑\fR\m[]5) + git:(my-branch 6\m[red]\fB↓\fR\m[]) + git:(my-branch 6\m[yellow]\fB⇵\fR\m[]5) +.fi + +In the three examples, the upstream branch is +.B remotes/origin/my\-branch, +and we are: ahead by 5 commits, behind by 6 commits, and diverged by 5/6 commits +respectively. + +.TP +.B %{remote} +This element functions the same as the +.B %{local} +element, except that the upstream branch +.B @{u} +is compared to the repository's default branch. + +.nf + git:(\m[green]\fB↑\fR\m[]5 my-branch) + git:(6\m[red]\fB↓\fR\m[] my-branch) + git:(6\m[yellow]\fB⇵\fR\m[]5 my-branch) +.fi + +In the three examples, the upstream branch is +.B remotes/origin/my\-branch, +the default remote branch is +.B remotes/origin/master, +and: my\-branch is ahead by 5 commits, master is ahead by 6 commits, and the two +are diverged by 5/6 commits respectively. + +The default branch is determined automatically. + +.TP +.B %{alert} +Outputs a customizable icon whenever the repository is in the middle of an +ongoing operation such as a merge, rebase, bisect, etc., or if the branch's +configured upstream no longer exists. + +.nf + git:(\m[yellow]\fB⚡\fR\m[]detached@2fb1cc17) +.fi + +The example shows us in the middle of a bisect session. Since we are bisecting, +.B HEAD +is detached, with the next revision to test checked out. + +See also, +.BR git\-precheck (1). + +.P +Below is a more complete example, showcasing many elements of the prompt +rendering at once in a fairly complex situation: + +.nf + o\-\-\-o\-\-\-o\-\-\-o\-\-\-o origin/master + \e + o\-\-\-o origin/my\-branch + \e + o\-\-\-o HEAD, my\-branch + + git:(\m[yellow]\fB⚡\fR\m[]3\m[yellow]\fB⇵\fR\m[]2 my-branch \m[green]\fB↑\fR\m[]2) 1\m[yellow]\fB≡\fR\m[] 2\m[green]\fBM\fR\m[] 1\m[yellow]\fBU\fR\m[] +.fi + +.B my\-branch +is checked out, with the shown branch topology. A merge from some other commit +has started, but could not complete automatically. Two files from the other +side of the merge have no conflicts and are already staged, however 1 file is in +conflict and must be resolved. There is also 1 saved stash being shown. + +.SH OPTIONS +.TP +.B \-v, \-\-version +Print the version of git\-sonar and exit. + +.TP +.B \-h, \-\-help +Display help for git\-sonar (opens this man page). + +.TP +.B \-\-fetch +git\-sonar will automatically fetch from remote repositories after a +configurable amount of time passes. A timestamp of the latest auto\-fetch is +stored in the +.B $GIT_DIR/lastupdatetime +file. The fetch operation is only triggered when the prompt renders, only runs +in the repository your shell is in, and executes in the background. + +.P +The remaining options affect the rendered prompt and are provided as a simple +way to disable features without the need to use a custom prompt format string. +For more powerful customization, see the "CONFIGURATION" section. + +.TP +.B \-\-no\-remote\-commits +Disable rendering the +.B %{remote} +prompt element, even if it is present in +.B $GIT_SONAR_PROMPT_FORMAT. + +.TP +.B \-\-no\-local\-commits +Disable rendering the +.B %{local} +prompt element, even if it is present in +.B $GIT_SONAR_PROMPT_FORMAT. + +.TP +.B \-\-no\-status +Disable rendering the +.B %{status} +prompt element, even if it is present in +.B $GIT_SONAR_PROMPT_FORMAT. +For simpler prompts, disabling this feature provides a decent speedup, but omits +a lot of information. + +.TP +.B \-\-no\-stash +Disable rendering the +.B %{stash} +prompt element, even if it is present in +.B $GIT_SONAR_PROMPT_FORMAT. + +.SH CONFIGURATION +Colors are customized by using ANSI color codes with the environment variables +listed below. However, note that these escape sequences (and any unprintable +characters used) need to be wrapped in markers that your shell uses to track the +length of the prompt and handle line wrapping. These markers will vary by shell +and it is the responsibility of the user to insert the correct ones when +exporting overrides for the variables below. The default colors use markers +that are compatible with bash. Overrides for zsh can be seen in the "USAGE" +section of this document. +.P +As a convention for this section, this syntax will be used to denote the use of +a default color in another variable: + +.nf + ${<color\-name>} := [prefix marker] \\033[XXXm [suffix marker] +.fi + +In cases where a default color is used, the markers remain configurable using +a pair of variables below. +.B XXX +represents the color attributes required by +.B <color\-name>. + +.TP +.B $GIT_SONAR_COLOR_PREFIX +The prefix escape code marker used by default colors. User provided variables +must insert their own markers and are unaffected by this value. + +Default: +.B \\\001 +(bash compliant) + +.TP +.B $GIT_SONAR_COLOR_SUFFIX +The suffix escape code marker used by default colors. User provided variables +must insert their own markers are are unaffected by this value. + +Default: +.B \\\002 +(bash compliant) + +.TP +.B $GIT_SONAR_DEFAULT_COLOR +The color which the terminal is reset to at the end of each prompt element. +This variable is mainly useful for preserving a background color inside the +git\-sonar prompt. + +Default: +.B ${reset} +(all terminal attributes cleared) + +.TP +.B $GIT_SONAR_PROMPT_COLOR +The text color used by the default prompt format string for the +.B 'git:(' ')' +characters surrounding the branch information. If the user provides their own +value for +.B $GIT_SONAR_PROMPT_FORMAT, +it is unaffected by this value. + +Default: +.B ${bright black} + +.TP +.B $GIT_SONAR_PROMPT_FORMAT +When inside a git repository, this string controls the format of the output +produced by git\-sonar. It functions similarly as a printf\-style format +string: most characters are output verbatim, and a format specifier syntax is +used to substitute output from the prompt elements: + +.nf + %{element-name} +.fi + +If +.B element\-name +is either prefixed or suffixed by a colon, the colon delimits a string that is +affixed to the element output if and only if the element has any output to +produce. For example, +.B %{[:stash:]} +produces [1\m[yellow]\fB≡\fR\m[]] if a stash is available, but the extra +brackets are omitted otherwise. The default format string utilizes this to add +optional spacing around elements which don't always appear active. + +See the "PROMPT ELEMENTS" section for a description of all possible outputs. + +.nf +Default: (space) git:(%{alert}%{remote: }%{branch}%{ :local})%{ :stash}%{ :status} +.fi + +.TP +.B $GIT_SONAR_FETCH_TIME +The number of seconds between automatic remote fetches when using +.B \-\-fetch. + +Default: +.B 300 +(5 minutes) + +.TP +.B $GIT_SONAR_ALERT_ICON +The symbol shown by the +.B %{alert} +prompt element. + +Default: +.B ${yellow}⚡ + +.TP +.B $GIT_SONAR_STASH_ICON +The symbol shown by the +.B %{stash} +prompt element. + +Default: +.B ${yellow}≡ + +.TP +.B $GIT_SONAR_BRANCH_COLOR +The text color used by the +.B %{branch} +prompt element when on a branch. + +Default: +.B $GIT_SONAR_DEFAULT_COLOR + +.TP +.B $GIT_SONAR_DETACHED_COLOR +The text color used by the +.B %{branch} +prompt element when +.B HEAD +is detached. + +Default: +.B $GIT_SONAR_DEFAULT_COLOR + +.TP +.B $GIT_SONAR_STATUS_SEPARATOR +The string used to separate the different change stages output by the +.B %{status} +prompt element. + +Default: +.B (space) + +.TP +.B $GIT_SONAR_AHEAD_ICON +The symbol shown by the +.B %{local} +and +.B %{remote} +prompt elements when the primary ref is strictly ahead of the secondary. + +Default: +.B ${green}↑ + +.TP +.B $GIT_SONAR_BEHIND_ICON +The symbol shown by the +.B %{local} +and +.B %{remote} +prompt elements when the primary ref is strictly behind the secondary. + +Default: +.B ${red}↓ + +.TP +.B $GIT_SONAR_DIVERGED_ICON +The symbol shown by the +.B %{local} +and +.B %{remote} +prompt elements when the primary and secondary refs each hold unique commits. + +Default: +.B ${yellow}⇵ + +.TP +.B $GIT_SONAR_STAGED_COLOR +The text color used by the +.B %{status} +prompt element for change indicators of changes staged in the index. + +Default: +.B ${green} + +.TP +.B $GIT_SONAR_UNSTAGED_COLOR +The text color used by the +.B %{status} +prompt element for change indicators of unstaged changes. + +Default: +.B ${red} + +.TP +.B $GIT_SONAR_UNMERGED_COLOR +The text color used by the +.B %{status} +prompt element for change indicators of unmerged paths (conflicted files). + +Default: +.B ${yellow} + +.TP +.B $GIT_SONAR_UNTRACKED_COLOR +The text color used by the +.B %{status} +prompt element for the untracked file indicator. + +Default: +.B ${white} + +.SH SEE ALSO +.BR git\-fetch (1), +.BR git\-log (1), +.BR git\-precheck (1), +.BR git\-stash (1), +.BR git\-status (1) + +.SH LICENSE +.B git\-sonar +is available under the terms of the +.B MIT +license. |