{"id":13507673,"url":"https://github.com/gbataille/gitHUD","last_synced_at":"2025-03-30T09:33:01.414Z","repository":{"id":44763416,"uuid":"46679402","full_name":"gbataille/gitHUD","owner":"gbataille","description":"command-line HUD for your git repo","archived":false,"fork":false,"pushed_at":"2023-11-18T07:07:03.000Z","size":2452,"stargazers_count":75,"open_issues_count":6,"forks_count":17,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-23T10:46:31.911Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gbataille.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"patreon":"gbataille"}},"created_at":"2015-11-22T20:49:10.000Z","updated_at":"2025-03-03T07:47:56.000Z","dependencies_parsed_at":"2023-02-08T05:02:07.295Z","dependency_job_id":"a05f2daf-8e5a-40f5-a83d-ad4efc0a65ba","html_url":"https://github.com/gbataille/gitHUD","commit_stats":{"total_commits":281,"total_committers":9,"mean_commits":31.22222222222222,"dds":0.09964412811387902,"last_synced_commit":"91ab91355683674545062cb3aa1670eb4a637888"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbataille%2FgitHUD","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbataille%2FgitHUD/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbataille%2FgitHUD/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbataille%2FgitHUD/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gbataille","download_url":"https://codeload.github.com/gbataille/gitHUD/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246301963,"owners_count":20755512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T02:00:37.655Z","updated_at":"2025-03-30T09:33:00.750Z","avatar_url":"https://github.com/gbataille.png","language":"HTML","readme":"[![Build Status](https://travis-ci.org/gbataille/gitHUD.svg?branch=master)](https://travis-ci.org/gbataille/gitHUD)\n[![Release](https://img.shields.io/github/release/gbataille/gitHUD.svg)](https://github.com/gbataille/gitHUD/releases)\n[![Hackage](https://img.shields.io/hackage/v/githud.svg)](https://hackage.haskell.org/package/githud)\n[![Hackage](https://img.shields.io/hackage-deps/v/githud.svg)](https://hackage.haskell.org/package/githud)\n\nAs you might have guessed from its name, githud is a heads up display for the\ncommand line that will show git information. The focus is on information and performance.\n\nIf you are as crazy as I am about your prompt, you might want to check my somewhat related project\n[envstatus](https://github.com/gbataille/envstatus)\n\n![Example]\nSee [Prompt explained](docs/PROMPT_EXPLAINED.md) for a detailled element by element description of what\nyou see\n\n_**Note:** this example is taken from the iTerm2 OSX terminal, with custom\ncolors from the Solarized Dark theme_\n\n* [Why githud?](#why_githud?)\n* [Install](#install)\n* [Setup](#setup)\n* [Configuration](#configuration)\n* [Understanding the githud prompt](#understanding-the-githud-prompt)\n* [Benefits](#benefits)\n* [Benchmarks](#benchmarks)\n* [Thanks](#thanks)\n\nWhy githud?\n-----------\n\nI was really psyched a few months ago (mid-2015) by\n[git-radar](https://github.com/michaeldfallen/git-radar). Git-radar does the exact\nsame thing as githud, but is implemented in shell. While I had a great time\nusing it for a while, I realized that on my particular setup, git-radar was\nintroducing a visible delay (\u003e200ms, too long for me) in the displaying of my\nprompt.\n\nAt that time, I was looking for an exercise to implement in Haskell, so that's\nhow I created githud\n\nInstall\n-------\n\nWhichever way you install githud, don't forget to complete the [Setup](#setup)\n\n### Mac OSX with brew\n\n_(Maintained on each release)_\n\n* link my tap\n\n```\nbrew tap gbataille/homebrew-gba\n```\n\n* install githud\n\n```\nbrew install githud\n```\n\n#### Binary packages on linux\n\n_Looking for contributor to provide a recipe (in github actions form?)_\n\n### With cabal and Nix\n\n_(Used in the development process, therefore it is maintained and up-to-date)_\n\nA Nix config is maintained in compatibility with the cabal file. So to be sure to use a compatible\nghc version, and corresponding libraries, just\n\n```sh\nnix-shell\ncabal v2-install\n```\n\n### With Stack\n\n_(Not maintained. Dev happens using Nix + Cabal. Don't hesitate to contribute)_\n\nStack is a haskell package manager. 1 command install can be found\n[here](https://docs.haskellstack.org/en/stable/README/)\n\ngithud is available on hackage, but some dependencies have to be explicited.\nYou need to add the following to the extra-deps in your stack.yml file\n\n``` ./.stack/global-project/stack.yaml\nextra-deps:\n- daemons-0.4.0\n- network-2.8.0.1\n```\n\nthen you can run\n\n```\nstack install githud\n```\n\n### With Cabal\n\n_(Not maintained. Dev happens using Nix + Cabal. Don't hesitate to contribute)_\n\ngithud is available on hackage. Therefore just get it as usual\n\n```\ncabal v2-install exe:githud\n```\n\nYou can then update your path to include your installation directory (typically `~/.cabal/bin`) or\ncopy the installed executable to a common location like `/usr/local/bin`\n\nSetup\n-----\n\nIf you simply call the githud executable, you'll get a short status of your\nrepository. It's meant to be called each time you display your prompt.\nTherefore you want to put it in your PS1 env variable.\n\nShells have some fancy way of managing prompt when you do things like\nautocompletion and the like. For that it needs to know the size of the prompt.\nSpecial characters used to express the color of the prompt need to be\nsurrounded by special markup for them not to be counted.\n\nGitHUD knows how to handle this. All you have to do is to run the program with\na parameter depending on your shell of choice and those special characters will be used in the\noutput\n\n#### Bash\n\n```\ngithud bash\n```\n\nFor example, in my `.bashrc` file, with the executable at\n`/usr/local/bin/githud`, I have a prompt definition that looks like that:\n\n```\nexport PS1=\"\\[\\033[0;37m\\][\\A]\\[\\033[0m\\] \\[\\033[0;36m\\]\\u\\[\\033[0m\\]\n\\W\\[\\033[0;32m\\]\\$(/usr/local/bin/githud bash)\\[\\033[0m\\]\\$ \"\n```\n\n_(it has a lot more things into it, including the current directory, the hour,\nand a prompt '$' terminating character)_\n\n#### ZSH\n\n```\ngithud zsh\n```\n\n_**Note**: Those special characters `%{` `%}` are only interpreted and hidden when\nzsh renders a prompt. If you simply call githud with this parameter 'zsh' from\nthe command line, you'll see them in the output!_\n\nPutting it together in my `.zshrc`, I have the following PROMPT variable with\nthe executable at `/usr/local/bin/githud`\n\n\n```\nsetopt PROMPT_SUBST\nexport PROMPT='%F{white}%T%F{cyan} %n%{$reset_color%} $(/usr/local/bin/githud zsh) $'\n```\n\n_(it has a lot more things into it, including the current directory, the\ncurrent user, the hour, and a prompt '$' terminating character)_\n\n#### Fish\n\nAdd this code to your config.fish file.\n\n```\nfunction fish_prompt\n  set_color white\n  echo -n [(date \"+%H:%M\")]\n  set_color cyan\n  echo -n (whoami):\n  set_color yellow\n  echo -n (prompt_pwd)\n  set_color $fish_color_cwd\n  echo -n (/usr/local/bin/githud)\n  set_color normal\n  echo -n \"\u003e \"\nend\n```\n\n#### TMUX\n\nProposed by @Thermatix\n\n```\ngithud tmux\n```\n\nPutting it together in my `.tmux.conf`, I have the following `status-right` variable with\n```\nset -g status-right '#{pane_current_command} #(~/.zsh/bin/githud_status \"#{pane_current_path}\")'\n```\nwhich necessitates a small script `~/.zsh/bin/githud_status`\n```\n#!/usr/local/bin/zsh -f\ncd $1 \u0026\u0026 /usr/local/bin/githud zsh\n```\n\nand the executable at `/usr/local/bin/githud`\n\n#### NONE\n\nProposed by @Thermatix\n\nYou can get a raw text output (no special formatting) by calling\n\n```\ngithud none\n```\n\nConfiguration\n-------------\n\nThe prompt format is nicely configurable. The defaults give you the look and\nfeel from the screenshot above, with a terminal configured with the Solarized\nDark theme colors.\n\nTo change those colors, or the markers used in the prompt:\n* Copy the `.githudrc` file from this repository into your home directory.\n  Then, from your home directory\n```\nwget https://raw.githubusercontent.com/gbataille/gitHUD/master/.githudrc\n```\n* Edit the file by uncommenting some fields and changing their values\n  (instructions are enclosed in the file)\n\nYou can control which section of the output are shown (if you want to mask\nsome) with the configuration keys starting with \"show\\_part\\_\"\n\n#### The fetcher daemon\n\n`githud` includes a companion daemon called `githudd`. This daemon will start the first time\n`githud` is invoked and will run forever.\n\nThis daemon will simply execute a `git fetch` periodically in the last git repository in which\n`githud` was executed. In the standard installation where you use `githud` in your prompt, this\nmeans that the daemon executes `git fetch` in the last git repository visited.\n\nThe `.githudrc` configuration file can contain the following configuration for the daemon (default\nvalues given here)\n```ini\n# Whether githud will launch the background daemon\nrun_fetcher_daemon=True\n# How long does the daemon sleep between cycles\ngithudd_sleep_seconds=30\n# Path where the githudd pid file will be stored. Needs to exist and be accessible by the current\n# user\ngithudd_pid_file_path=/usr/local/var/run/githudd.pid\n# Path where the githudd lock file will be stored. Needs to exist and be accessible by the current\n# user\ngithudd_lock_file_path=/$TMPDIR/githudd.lock\n# Path where the githudd socket file will be stored. Needs to exist and be accessible by the current\n# user\ngithudd_socket_file_path=/usr/local/var/run/githudd.socket\n# Path where the githudd stdout/stderr capture logfile will be store.\n# Githudd logs can be verbose. They are here for debugging only. It is not advised that you\n# activate them\n# Use the value /dev/null to disable the logs\ngithudd_log_file_path=/dev/null\n```\n\nTo stop the daemon, you can simply do\n```bash\npkill githudd\n```\n\nNote that due to instability, the daemon is currently disabled by default\n\nThe health of the `githudd` daemon is indicated by a red hearth (broken when unhealthy) at the start\nof the prompt (only when the daemon is activated)\n\n\nUnderstanding the githud prompt\n-------------------------------\n\nSee [Prompt explained](docs/PROMPT_EXPLAINED.md)\n\nBenefits\n--------\n\n- githud is fast (on my system, about twice as fast as git-radar, with exec\n  times below 100ms)\n- githud is easily maintainable through proper test coverage\n\nThe only downside compared to git-radar is that you need to compile it on your\nplatform, as opposed to being just shell.\n\nOn Mac, it's now easy since I packaged it as a brew bottle. For Linux, I'm\nwaiting for contributions to put it in RPM or DEB packages :)\n\nBenchmarks\n----------\n\nSo of course, I wanted to check that whatever I was doing was useful. So I did\na couple of benchmarks with the Haskell Criterion library. It's based on my\nsystem and does not guarantee any performances but it gives you an idea of the\nimprovements. Here goes:\n* git-radar - full shell implementation\n* githud-syncIO - with normal IOs done one at a time\n* githud-asyncIO - with IOs programmed asynchronously for better performance.\n\n![Bench]\n\n[Here](./bench/bench.html) you can find the details\n\nFor information: I ran that on a Macbook Pro 13\", 2014, fully boosted, running\nwith iTerm 2, tmux, oh-my-zsh, inside a git repo with quite some information\nto parse\n\nThanks\n------\n\nWell, my thanks to [git-radar](https://github.com/michaeldfallen/git-radar) for the great idea, and to\n[guibou](https://github.com/guibou) for the code\nreviews\n\n\n[Example]: ./images/prompt.png\n[Bench]: ./bench/bench.png\n","funding_links":["https://patreon.com/gbataille"],"categories":["Commandline Utilities"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbataille%2FgitHUD","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgbataille%2FgitHUD","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbataille%2FgitHUD/lists"}