gerph/ls-with-git-status

lsg: List files with git status information

lsg: ls with git information

Introduction

The lsg tool is intended to give information on files in a directory in the same style as the ls command - but adding more information about the git status of those files. The idea is to make it possible to see the git status in the same style as the ls command.

The tool is known to work on linux (Ubuntu), and Mac OS (10.12 to 10.14), and probably works on other systems

What it looks like

An example 'asciicast' can be seen here: https://asciinema.org/a/219091

What it can show

Files within a git repository:

• File changes are only shown in braces.
• Untracked and ignored files are shown:
  • {untracked} - File is not known to git
  • {ignored} - File is listed as a pattern in .gitignore
• Changed files in the working tree are shown:
  • {modified locally, 3 lines} - Changed in working tree, 3 lines affected (added or deleted)
  • {deleted locally} - File has been deleted in working tree
• Changed files in the cache are shown:
  • {staged, 3 lines} - Changes have been staged, 3 lines affected (added or deleted)
  • {deleted} - File has been marked for deletion in cache
  • {added} - File has been marked for addition in cache
  • {renamed} - File has been renamed to this name in the cache
• Merge status is show:
  • {unmerged, both added} - File was added by merge, and we added it as well.

Directories within a git repository:

• Only untracked or ignored state is shown (to make lists faster):
  • {untracked} - Directory is not known to git
  • {ignored} - Directory is listed as a pattern in .gitignore

Repositories and submodules:

• Branch details are in brackets:
  • (master) - directory is at the head of branch master
• Relative location compared to upstream is shown with arrows after the name
  • (master￪1) - 1 commits locally ready to be pushed
  • (master￬7) - 8 commits available in fetched upstream
  • (master⊗) - no upstream is configured
  • (master~2○) - detached head
• Submodule reference changes are described within the brackets:
  • (master added) - Submodule has been added
  • (master 8 forward) - Submodule has moved 8 changes forward in the same tree (in working tree)
  • (master 2 back) - Submodule has moved 2 changes backward in the same tree (in working tree)
  • (master new ref) - Submodule has changed to a ref unrelated to the old tree (in working tree)
  • (master staged 1 forward) - Submodule has moved 1 changes forward in the same tree (in the cache)
• Summary of changes to the files within the submodule are shown in braces:
  • {1 modified} - 1 file has been changed in the working tree
  • {2 staged} - 2 files have been changed and staged in the working tree
• All the above options can be combined.

Requirements

• bash - version 3 or 4; although it'll be slower on 3 due to lack of associative arrays
• git - obviously
• ls
  • BSD version supplied with Mac OS or a GNU version
  • colour is supported (and explicitly forced)
• perl - version 5 upward (although might be version 3 compatible)
• grep - BSD version supplied with Mac OS or a GNU version
• sed - BSD version supplied with Mac OS or a GNU version

How to use it

The lsg command can be used almost exactly like the ls command. The actual operation of the command is to invoke ls and then post-process the output, so most of the ls switches and uses are exactly the same. However, because it only handles single columns, the switches related to multi-column, comma-separated and dired formats are not usable.

Because the command expects to use colour, colouring will be forced in the ls output.

There is an extra switch that the lsg tool adds for showing nested subdirectories. The --nest (or --nest=<depth>) switch can be used to list subdirectories as well.

Configuration

Colouring for the output is taken from git configuration. If you wish to change the colours used, the following configurations are read:

config name	usage	default
color.status.branch	Branch name	cyan
color.status.added	Added file	green
color.status.updated	Staged file	green
color.status.changed	Modified file	yellow
color.status.untracked	Not known to git	red
color.status.unmerged	Not yet merged	red bold
color.status.ignored	Ignored by .gitignore	dim

Towards the top of the code, there are a number of constant symbols assigned which define the symbols used to show some states. Only the branch state and relative position in the git history use symbols; otherwise words are used to describe the status.

ls-with-git-status's Issues

bad array subscript when running inside ignored directory

When running lsg inside a gitignored directory I'm getting:

lsg: line 605: git_status[$name]: bad array subscript

This is with Git 2.26.2 and Bash 5.0.17 on Linux.

lsg --help is garbled

Thanks for the great tool[1]!

When running lsg --help it attempts to pass through the ls --help which works, but gets malfored; probably because some keywords are replaced by regexpes.

It may also have to do with my locales:

$ env | grep -e "LANG" -e "LC_" | sort

LANG=nl_NL.UTF-8
LANGUAGE=nl:en_GB:en
LC_ADDRESS=nl_NL.UTF-8
LC_IDENTIFICATION=nl_NL.UTF-8
LC_MEASUREMENT=nl_NL.UTF-8
LC_MONETARY=nl_NL.UTF-8
LC_NAME=nl_NL.UTF-8
LC_NUMERIC=nl_NL.UTF-8
LC_PAPER=nl_NL.UTF-8
LC_TELEPHONE=nl_NL.UTF-8
LC_TIME=nl_NL.UTF-8

$ lsg --help

Gebruik:  ls [OPTIE...] [BESTAND...]
Toont informatie over de gegeven BESTANDen (standaard over de huidige map).

De items worden alfabetisch gesorteerd als geen van de opties '-cftuvSUX'
noch '--sort' gegeven is.

(Een verplicht argument bij een lange optie geldt ook voor de korte vorm.)
-a, --all                  ook de namen tonen die beginnen met een '.'
-A, --almost-all           als '-a', maar de items '.' en '..' weglaten
--author               (met '-l') de auteur van elk bestand tonen
-b, --escape               niet-grafische tekens tonen als codes in C-stijl
--block-size=GROOTTE   de te tonen groottes schalen naar deze waarde;
'--block-size=M' bijvoorbeeld toont de groottes
in eenheden van 1.048.576 bytes; zie hieronder
-B, --ignore-backups       geen namen tonen die eindigen op '~'
-c                         met '-lt': op 'ctime' sorteren en deze tonen (de
tijd van de laatste statusinformatiewijziging);
met '-l': op naam sorteren en 'ctime' tonen;
anders: op 'ctime' sorteren, recentste eerst
-C                         de items in kolommen presenteren
--color[=WANNEER]      bestandstypen met kleuren onderscheiden;
WANNEER is 'always' (altijd), 'never' (nooit),
of 'auto' (uitvoerapparaatafhankelijk);
zie hieronder voor meer informatie
-d, --directory            alleen mapnamen tonen, niet hun inhoud,
en symbolische koppelingen niet volgen
-D, --dired                uitvoer produceren voor de 'dired'-modus van Emacs
-f                         hetzelfde als '-a -U' zonder '-l -s --color'
-F, --classify             achter elk item het type aanduiden (één van */=>@|)
--file-type            idem, maar '*' niet tonen
--format=WOORD         te gebruiken opmaak; WOORD kan zijn 'commas' (-m),
'across' of 'horizontal' (-x), 'vertical' (-C),
'long' of 'verbose' (-l), 'single-column' (-1)
--full-time            hetzelfde als '-l --time-style=full-iso'
-g                         als '-l', maar geen eigenaar tonen
--group-directories-first
mappen vóór bestanden groeperen; kan aangevuld
worden met een '--sort', maar gebruik van
'--sort=none' of '-U' deactiveert groepering
-G, --no-group             bij een uitgebreide lijst geen groepsnaam tonen
-h, --human-readable       groottes in leesbare vorm tonen (samen met -l/-s))
--si                   idem, maar machten van 1000 i.p.v. 1024 gebruiken
-H, --dereference-command-line
symbolische koppelingen op opdrachtregel volgen
--dereference-command-line-symlink-to-dir
symbolische koppelingen op opdrachtregel die naar
een map verwijzen volgen
--hide=PATROON         de namen die voldoen aan PATROON niet tonen
(geldt niet samen met '-a' of '-A')
--hyperlink[=WHEN]     hyperlink file names; WHEN can be 'always'
(default if omitted), 'auto', or 'never'
--indicator-style=WIJZE  op deze wijze achter elk item het type aanduiden;
WIJZE kan zijn: 'none' (standaard), 'slash' (-p),
'file-type' (--file-type) of 'classify' (-F)
-i, --inode                het indexnummer van elk bestand tonen
-I, --ignore=PATROON       de namen die voldoen aan PATROON niet tonen
-k, --kibibytes            blokken van 1024 bytes gebruiken bij schijfgebruik
-l                         uitgebreide bestandsinformatie tonen
-L, --dereference          bij het tonen van bestandsinformatie voor een
symbolische koppeling, de informatie over het
bestand waar de koppeling naar verwijst tonen
in plaats van over de koppeling zelf
-m                         geen kolommen maar kommagescheiden lijst tonen
-n, --numeric-uid-gid      als '-l', met numerieke gebruikers- en groeps-ID's
-N, --literal              de itemnamen tonen zonder aanhalingen of escapes
-o                         als '-l', maar groepsinformatie niet tonen
-p, --indicator-style=slash
een '/'-indicator achter mapnamen toevoegen
-q, --hide-control-chars   een '?' tonen in plaats van niet-grafische tekens
--show-control-chars   niet-grafische tekens tonen zoals ze zijn
(standaard, tenzij uitvoer naar terminal gaat)
-Q, --quote-name           itemnamen omsluiten met aanhalingstekens
--quoting-style=STIJL  te gebruiken aanhalingsstijl voor items;
STIJL kan zijn: 'literal' (-N), 'locale',
'shell', 'shell-always', 'shell-escape',
'shell-escape-always', 'c' (-Q), 'escape' (-b)
-r, --reverse              de sorteervolgorde omdraaien
-R, --recursive            submappen recursief tonen
-s, --size                 toegewezen aantal blokken tonen voor ieder bestand
-S                         op bestandsgrootte sorteren (grootste eerst)
--sort=WIJZE           te gebruiken sorteerwijze;
WIJZE kan zijn: 'size' (-S), 'time' (-t),
'none' (-U), 'version' (-v), 'extension' (-X)
--time=SOORT           (met '-l') te tonen soort tijd;
SOORT kan zijn: 'ctime' of 'status' (-c),
'atime' of 'access' of 'use' (-u); gegeven
tijdssoort ook gebruiken als sorteersleutel
als '--sort=time' gegeven is (nieuwste eerst)
--time-style=STIJL     (met '-l') tijden volgens deze stijl tonen;
STIJL kan zijn: 'iso', 'long-iso', 'full-iso',
'locale',  of '+OPMAAK';
OPMAAK wordt geïnterpreteerd zoals bij 'date';
als OPMAAK de vorm OPMAAK1<nieuweregel>OPMAAK2
heeft, dan geldt OPMAAK1 voor oude bestanden
en OPMAAK2 voor recente bestanden;
als STIJL 'posix-' als voorvoegsel heeft, dan
geldt deze alleen buiten de POSIX-taalregio
-t                         op de tijd van laatste wijziging sorteren
-T, --tabsize=AANTAL       te gebruiken tabbreedte in plaats van 8
-u                         met -lt: op toegangstijd sorteren en deze tonen;
met -l: toegangstijd tonen en op naam sorteren;
anders: op toegangstijd sorteren (nieuwste eerst)
-U                         de items ongesorteerd tonen, op plaatsingsvolgorde
-v                         logisch sorteren op (versie)nummers in de naam
-w, --width=BREEDTE        te gebruiken schermbreedte; 0 betekent onbegrensd
-x                         de items per regel tonen i.p.v. in kolommen
-X                         alfabetisch sorteren op bestandsextensie
-Z, --context              beveiligingscontext van elk bestand tonen
-1                         één item per regel tonen; onderdruk \n met -q of -b
--help      deze hulptekst tonen en stoppen
--version   programmaversie tonen en stoppen

GROOTTE is een geheel getal met een optionele eenheid (bijv. 10K is 10*1024).
Mogelijke eenheden zijn: K, M, G, T, P, E, Z, Y (machten van 1024)
of KB, MB, ... (machten van 1000).  Bijvoorbeeld: 10MB is 10*1000*1000.

Het gebruik van kleuren om bestandstypes te onderscheiden kan uitgeschakeld
worden met '--color=never' (standaard).  Met '--color=auto' produceert 'ls'
alleen kleurcodes als standaarduitvoer verbonden is met een terminal.
Omgevingsvariabele LS_COLORS kan deze instellingen wijzigen.  Gebruik
het commando 'dircolors' om deze variabele in te stellen.

�[1mDe afsluitwaarde is�[m:
0  indien OK,
1  bij kleine problemen (bijv. geen toegang tot een submap),
2  bij serieuze problemen  (bijv. geen toegang tot argument op opdrachtregel).

Online hulp bij GNU coreutils: <http://www.gnu.org/software/coreutils/>
Meld vertalingsfouten in 'ls' aan <[email protected]>.
Volledige documentatie is beschikbaar op: <http://www.gnu.org/software/coreutils/ls>
of lokaal via: info '(coreutils) ls invocation'

---

[1] I found this because you mentioned it as answer to a question on Stackoverflow.