eshell-info-banner.el/README.org

#+title: eshell-info-banner.el
#+author: Lucien Cartier-Tilet
#+email: lucien@phundrak.com
* Introduction
~eshell-info-banner.el~ is a utility for creating an informative banner,
akin to ~fish_greeting~ but for Eshell. But an image is worth a thousand
words, let’s see how it looks like:

#+caption: Screenshot of the default Eshell information banner
[[file:img/screenshot.png]]

This will be displayed every time you open a new Eshell instance, or
if you invoke ~eshell-info-banner~ from it.

This package is geared towards Linux in particular, I am pretty sure
it will not work on Windows, and there will probably be bugs on
macOS. PR are welcome if you want to fix that!

* Installation 
A couple of options are available for installing
~eshell-info-banner.el~. The first one is to clone the repository in
your ~load-path~ and add the following to your ~.emacs~ or your ~init.el~:
#+begin_src emacs-lisp
  (require 'eshell-info-banner)
  (add-hook 'eshell-banner-load-hook 'eshell-info-banner-update-banner)
#+end_src

In my case, I prefer using ~use-package~ with ~straight~:
#+begin_src emacs-lisp
(use-package eshell-info-banner
  :defer t
  :straight (eshell-info-banner :type git
                                :host github
                                :repo "phundrak/eshell-info-banner.el")
  :hook (eshell-banner-load . eshell-info-banner-update-banner))
#+end_src

I personally also added ~:build t~ in the straight recipe to ensure
Emacs compiles my package, both to ~.elc~ and ~.eln~ files (I am on Emacs
28.0, ~feature/native-comp~ got merged into ~master~!)

There is probably a similar way to install it with pure ~straight.el~ or
~quelpa~, but I’m not knowledgable enough for that, feel free to create
a PR to add some more installation instructions!

There is currently no plans of making this package available on MELPA
or non-gnu elpa.

* Customizing
A couple of variables can be edited by the user in order to configure
~eshell-info-banner.el~:
- ~eshell-info-banner-shorten-path-from~ :: Maximum length of the mount
  path of a partition before it gets abbreviated. Set it to ridiculous
  numbers in order to disable it (something like ~1000~ should be more
  than enough). Default value: ~7~
- ~eshell-info-banner-width~ :: *Minimum* width of the banner. Be aware
  the banner will automatically select the minimal width required to
  display everything it wants to display if ~eshell-info-banner-width~
  is too small. Default value: ~80~
- ~eshell-info-banner-progress-bar-char~ :: Character to fill the
  progress bar with. Default value: ~=~
- ~eshell-info-banner-warning-percentage~ :: Percentage from which the
  level should be displayed as a warning. Default value: ~75~
- ~eshell-info-banner-critical-percentage~ :: Percentage from which the
  level should be displayed as critical. Default value ~90~

Don’t like the colors used by the package? They should follow by
default your theme, but you can customize the following faces:
- ~eshell-info-banner-background-face~ :: Used for filling the empty
  part of progress bars
- ~eshell-info-banner-normal-face~ :: Used for filling the progress bar
  when on normal levels
- ~eshell-info-banner-warning-face~ :: Used for filling the progress bar
  when on warning levels
- ~eshell-info-banner-critical-face~ :: Used for filling the progress
  bar when on critical levels

* My computer doesn’t have a battery, will this still work?
As you can see, one line shows you your battery level. Il will start
to warn you in a reverse way compared to the other progress bars, as
it should for battery levels –a fully charged battery at 100% is not
at a critical level, but at 0% it would be.

However, you might be on a desktop or any kind of computer that does
not have a battery, so… what do? Don’t worry, /Emacs will automatically
detect whether you have a battery or not/ and will only display this
line if you have one. If you don’t have a battery, the only difference
is you will have one less line than laptop users.

* Upcoming changes
Here are some upcoming changes I hope I’ll make in the future. If you
see a feature still hasn’t been implemented and you wish to implement
it, don’t hesitate to contribute and submit a PR!

** Better partitions detection
I wish to make the partitions detection a bit more configurable,
only partitions which filesystem is located in ~/dev~ are detected and
shown, I would like to allow people to make them discoverable
through their mountpoint instead through a configurable
alist. Change to come in future versions!

** Better support for other OSes
Displaying the OS name only works on systems that have an
~/etc/os-release~ file and ~df~ available in Eshell’s path —i.e. it will
not work on Windows, and probably not on macOS. This should be fixed
someday. (And *BSD maybe?)

* License
~eshell-info-banner.el~ is available under the GNU GPL-3.0 license. You
can find the full text in [[file:LICENSE.md][LICENSE.md]].