git-functions

Install git-functions to improve your git user experience with gitshell

Rationale

Every comfortable command-line UI should be verbose enough to be descriptive and self-explanatory and IMHO git achieved this goal very well. However, for intensive use - after having learned the command-line UI - verbosity impairs productivity and there is no way to avoid writing git in front of every command unless a functions-set wrap layer is used. This is the point in which git-functions arrives and aims to help those whose hands wish to be faster than their minds.

Have fun <3

About using the bash

The dash which is the standard by default shell in GNU/Debian Linux is about 2x faster than bash to execute commands and probably bash is the slowest shell of all. However, bashism are somewhat powerful shell-scripting tricks and moreover, the user interaction with small functions does not require any particular performance to be acceptable and in any case git is the real bottle-neck in performances especially when it queries a remote host.

Restricted shell

After the v0.4-rc1 the development went towards allowing the function to wrap git only into a restricted shell which is the bare minimum requirement to offer these shortcuts as a remote service. However, the limitations of the restricted shell could be easily by-passed leveraging a PATH. In fact, usually bash is in the PATH so it can be executed in interactive mode bash -i without limitations.

This shows clearly that rbash is not sufficient to restrict the user but also the environment should be controlled and usually the easy way to achieve this goal is to let the users play into a chroot-ed-environment specifically prepared

Usage

Just to give it a try, source the git.shell in your environment and call them in your git local repository

GFRELOAD=1 source git.shell

this file also source the colors.shell in order to produce a color full output while functions will be loaded when gitshell will be lauched.

Installation

To install in your system in a way they will be loaded by ~/.bashrc use this script without any argument

git clone https://github.com/robang74/git-functions.git
cd git-functions
./install.sh [ uninstall | update | reinstall | help ]

then follow the instructions, in particular source the git.shell in your current bash environment. To install the development version switch the branch with git switch devel and then run the installer from that branch.

Alternatively, you can do a remote installation with these commands

branch=main
repo=https://raw.githubusercontent.com/robang74/git-functions
wget $repo/$branch/install.sh -O - | bash

You might want to change the branch in devel but that branch, from time to time, could be totally broken. Other branches might have the same problem. However, also for the main branch, it is not assured of the lack of bugs.

Usage

After installation your .bashrc will be modified in such a way the gitshell will be defined as a function. Calling it - in your git repository - will give you the access to the wrap layer:

cd my-repo.git
gitshell
gfhelp

This command will display the functions available which are reported and briefly described here below. If you need more functions, feel free to add to the source code and share the change with the author. Or ask for an addition.

API changes

ff, sw: in git use -w (ignore blank spaces) as default, opt:-r added
lsrmt: was a replica of rmt now is a short for rmt -v
gfreload: opt:-f added to reload a single function

List of the functions

The following list is divided for class of usage and roles. Only the main functions are loaded by ~/.bashrc in the user bash environment while all the others are available inside the gitshell environment.

Main functions

gitshell: spawns a restricted shell with the git-funtcions environment
gfupdate: update the installation and reload the git-functions
gfhelp: like gflist but in a fancier way
gflist: list the functions available
gfreloadafunc: reload a single function
gfreload: reload the functions, opt:-f reload a single function

Service functions

cdtop: change directory to the top level of the repository and prints the full path
redef_git: redefine the function _git() which is used internally
reset_git: reset _git() to the default command git
noopts: print every arg that does not start with minus
ps1p: print a custom PS1 for git users
ps1s: set the custom PS1 for git users
egnc: function alias for egrep --color=never
less: function alias for command less -Fr
ugit: unbuffered version of git -P
ll: short for 'ls -al' with colors
eg: short for 'egrep` with colors

Example of redef_git and reset_git usage:

redef_git -u # every functions of this wrapper will use `ugit` instead of `git`
redef_git 'git -P "$@"'      # of this wrapper will use `git` with no pager
reset_git    # every functions of this wrapper will use `git` as default

Configure functions

pcache: set the password cache for 1h of inactivity, deal with .gitpasswd
editorset: set your default editor

Operative functions

opst: shows the current operation pending: merge, rebase or cherry-pick
todo: short for git --edit-todo, arg: c,m,r or current operation
cont: short for git --continue, arg: c,m,r,ce or current operation
abrt: short for git --abort, arg: c,m,r,ce or current operation
skip: short for git --skip, arg: c,m,r or current operation

Functions which alter also the remote repository

push: short for git pull
fpush: short for git push --force
repshrink: clean the reflog and shrink the repository
tagmv: move a tag to hash (as args) and push the changes
tagadd: add a tag to a commit (sha as arg) and push tags
tagdel: del a tag (as arg) and push the change
tagren: rename a tag and push the change
rmtadd: add a remote repository to the local
rmtdel: delete a remote repository
rmt: short for git remote

Functions which alter the local repository, only

forig: short for git fetch origin
frmt: short for git fetch, default the first in rmt or args with opt -a:--all
search: search for a string in all the commits and report the first found, arg string
irb, irebase: rebase starting from the hash passed or ~n/-n for HEAD~n
amd, amend: shorts for git amendbut with opt:-a doesadd -m`
add: short for git add but opt:-m add all the modified items
pa: format patch apply and create signed commit
ce: commit edit within a restricted shell
cr: commit reword, a single SHA as arg
ren: short for git mv
cm: short for git commit --signoff
co: short for git checkout
pull: short for git pull
rpull: short for git pull --rebase
rcont: short for git rebase --continue
stash: short for git stash
pop: short for git stash pop
chpk: short for git cherry-pick
rst(): short for git reset, opt -h:--hard
res(): short for git restore, opt -s:--staged, -h:hres()
hrst(): short for git reset --hard, opt -r:remote
sres(): short for git restore --staged
hres(): it performs sres() and then co()
ampatch(): short for git amend a patch/set
amff(): short for git am --show-current-patch=diff

Functions which do NOT alter the repositories

hconv: convert the hash reference into a standard 7-chars hash
lg: show the log in a compact and fancy way, SHAs or files as args
lgnc: the same of lg but without colors, for scripting
lgrpnc: the same of lgrp but without colors, for scriptings
lt: like lg but with all branches shown, files as args
lg1: like lg but just the first line
rl, reflog: shorts for git reflog
sf: show the file involved in a commit, SHAs as args
st: short for git status, opt:-m shows what add -m uses
sw: short for git show with sf after, opt:-P for no pager
ff: short for git diff -w, opts -s:staged -o:origin -r:remote
fpatch: do a git format-patch for the commit, SHA and opts in arg
bsw: short for git switch, the branch name as arg or - for the last
lgrp: find a string into the lg output, opts -s:SHAs-only -1:first only
lsbr: show the list of branches, arg branch name, opt: -r:remotes, -a:all
lsrmt: short for rmt -v, it shows the verbose list of remotes sources
mgrp: search a 'string' into st -m changed file or from hash, default HEAD or ~n/-n for HEAD~n
rcur: remote origin which the current branch is tracking, opt:-c --show-current only
rbcur: remote branch which the current brach is tracking
hcur: short for git rev-parse --short HEAD
bcur: short for git branch --show-current
lstag, tagl: shorts for git tag -l

Command execution on multiple branches

This is a special function used to execute commands (cmds) on multiple branches:

for-all-other-branches: execute the args as commands for the branches
- --: per default runs over all the branches but not the current one
- -a: all the branches included the current
- -p: git pull before cmds
- -r: git pull --rebase before cmds
- -n: not fail despite the last command failure
- -s: git stash before go and git stash pop when returns
- -f: fetch all the remotes before starting otherwise run only on locals

A custom branches selection could be specified in this way:

BRANCHES="uno due tre" for-all-other-branches 'cmds ${branch}'

The branch variable is defined in the loop and its value is the branch name on which commands are currently executing. The single quotes around the commands string are necessary to avoid that the variable is expanded before starting the loop.

In case the last command fails then the loop stops and spawns an emergency bash in that shell - which is restricted - the operator can handle the issue and then decide to proceed further with exit or definitely stop with exit 1.

Switch to branch 'devel'
Your branch is up-to-date with 'origin/devel'.

branch: devel, KO
fix the problem and then enter 'exit'
or enter 'exit 1' to abort completely

+git:devel> exit 1

Password cache

The use of the password cache function pcache could undermine your git remote repository security especially if used in combination with .gitpasswd. Moreover the use of the password cache or saving your git password in plain text in a file of your workstation disk could go against your company security policies. For extra security you can disable this function with

unset pcache

You might also want to add after the source git.function in your ~/.bashrc to make this choice as the default one. However, gfreload and gfupdate will load again into your current bash environment. To avoid this risk, then use:

unset pcache gfreload gfupdate

So, no one of these functions will be able to interfere with your security policy but you will need to use install.sh update to update your git-functions installation.

The alternative is to store the password in your home git global config or in the current git local config and pcache will retrieve your password from there.

The first time that pcache runs, it would be better setting the git username:

pcache --user $git_my_user_name

Otherwise the username will be asked by the cache manager but will be lost when the cache will expire. Setting the user works on https remote repositories.

isatty() override

To improve dramatically the fancy coloured output combined with some features like grepping and lessing, it has been used the trick to override isatty() using a small piece of code isatty_override.c which produces .so library:

LD_PRELOAD="${path}/isatty_override.so" git -P "$@"

This is an example of usage which resembles the core of the 'ugit' function.

License

Almost all the files are under one of many FOSS licenses and the others are in the public domain. Instead, the composition of these files is protected by the GPLv3 license under the effects of the Copyright Act, title 17. USC §101:

Under the Copyright Act, a compilation [EdN: "composition" is used here as synonym because compilation might confuse the technical reader about code compiling] is defined as a "collection and assembling of preexisting materials or of data [EdN: data includes source code, as well] that are selected in such a way that the resulting work as a whole constitutes an original work of authorship."

This means, for example, that everyone can use a single MIT licensed file or a part of it under the MIT license terms. Instead, using two of them or two parts of them implies that you are using a subset of this collection which is a derived work of this collection which is licensed under the GPLv3, also.

The GPLv3 license applies to the composition unless you are the original author of a specific unmodified file. This means that every one that can legally claim rights about the original files maintains its rights, obviously. Therefore the original authors do not need to undergo the GPLv3 license applied to the composition and they maintains their original right in full. Unless, they use the entire composition or a part of it for which they had not the rights, before.

Some files, documents, software or firmware components can make an exception to the above general approach due to their specific copyright and license restrictions. In doubt, follow the thumb rule of fair-use.

In this project, the copyright notice, the license and the author is reported in each file header and here just listed:

colors.shell: MIT
isatty_override.c: MIT
git-commit-edit: public domain
git-isar-send-patch: GPLv3
git.functions: GPLv3
cr-editor.sh: GPLv3
install.sh: GPLv3
git.shell: GPLv3

For further information or requests about licensing and how to obtain a fork suitable for your own business, please write to the project maintainer and copyleft owner.

Author

Roberto A. Foglietta roberto.foglietta@gmail.com