eshell-info-banner.el/README.org

#+title: eshell-info-banner.el
#+author: Lucien Cartier-Tilet
#+email: lucien@phundrak.com
[[https://melpa.org/#/eshell-info-banner][file:https://melpa.org/packages/eshell-info-banner-badge.svg]]
[[https://stable.melpa.org/#/eshell-info-banner][file:https://stable.melpa.org/packages/eshell-info-banner-badge.svg]]

* 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 (using the nord theme from ~doom-themes~)
[[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!

* Table of Contents                                                :TOC_2_gh:
- [[#introduction][Introduction]]
- [[#recent-breaking-changes][Recent Breaking Changes]]
  - [[#081][~0.8.1~]]
  - [[#070][~0.7.0~]]
- [[#installation][Installation]]
- [[#customizing][Customizing]]
  - [[#custom-variables][Custom Variables]]
  - [[#faces][Faces]]
- [[#my-computer-doesnt-have-a-battery-will-this-still-work][My computer doesn’t have a battery, will this still work?]]
- [[#advice-for-windows-users][Advice for Windows users]]
- [[#contributing][Contributing]]
- [[#license][License]]

* Recent Breaking Changes
** ~0.8.1~
Version ~0.8.1~ removes the optional argument ~REMOTE~ from
~eshell-info-banner--executable-find~. It now only acts according to the
user’s preference set with ~eshell-info-banner-tramp-aware~.

** ~0.7.0~
Version ~0.7.0~ renames several functions to conform with the Elisp
Coding Conventions.
| Old Name                                           | New Name                                           |
|----------------------------------------------------+----------------------------------------------------|
| ~eshell-info-banner--ge-mounted-partitions/duf~      | ~eshell-info-banner--ge-mounted-partitions-duf~      |
| ~eshell-info-banner--get-mounted-partitions/df~      | ~eshell-info-banner--get-mounted-partitions-df~      |
| ~eshell-info-banner--get-mounted-partitions/windows~ | ~eshell-info-banner--get-mounted-partitions-windows~ |
| ~eshell-info-banner--get-mounted-partitions/darwin~  | ~eshell-info-banner--get-mounted-partitions-darwin~  |
| ~eshell-info-banner--get-mounted-partitions/gnu~     | ~eshell-info-banner--get-mounted-partitions-gnu~     |
| ~eshell-info-banner--get-memory/gnu~                 | ~eshell-info-banner--get-memory-gnu~                 |
| ~eshell-info-banner--get-memory/unix~                | ~eshell-info-banner--get-memory-unix~                |
| ~eshell-info-banner--get-memory/windows~             | ~eshell-info-banner--get-memory-windows~             |
| ~eshell-info-banner--get-os-information/windows~     | ~eshell-info-banner--get-os-information-windows~     |
| ~eshell-info-banner--get-os-information/gnu~         | ~eshell-info-banner--get-os-information-gnu~         |
| ~eshell-info-banner--get-os-information/darwin~      | ~eshell-info-banner--get-os-information-darwin~      |

The following function was removed:
- ~eshell-info-banner--get-memory/darwin~

The following alias (replacing an old function) was removed:
- ~eshell-info-banner--get-memory/bsd~

* 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

If you use ~use-package~ only and install the package from MELPA, you
can then install it like so:
#+begin_src emacs-lisp
  (use-package eshell-info-banner
    :ensure t
    :defer t
    :hook (eshell-banner-load . 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
    :ensure t
    :defer t
    :straight (:build t)
    :hook (eshell-banner-load . eshell-info-banner-update-banner))
#+end_src

You can just use ~:straight t~ if you do not want to ensure the package
gets compiled by Emacs.

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!

* Customizing
** Custom Variables
A couple of variables can be edited by the user in order to configure
~eshell-info-banner.el~:
- ~eshell-info-banner-partition-prefixes~ :: Filter for which
  mountpoints are to be shown to the user. By default, only partitions
  mounted on a filesystem (as displayed by the command ~df -Hl~)
  prefixed by ~/dev~ are shown, but you can modify it by adding other
  prefixes to this list. For instance, to detect ZFS roots, you can
  set its value to ~("/dev" "zroot")~.

  Default value: ~("/dev")~
- ~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~
- ~eshell-info-banner-tramp-aware~ :: When using Eshell through TRAMP,
  you can decide whether ~eshell-info-banner~ will display information
  about the remote system you are connected to or only display
  information about your local system. To achieve this, set
 ~eshell-info-banner-tramp-aware~ to ~t~ to display information on the
  remote system or to ~nil~ to keep local information only.

  Default value: ~t~
- ~eshell-info-banner-use-duf~ :: Whether or not to use [[https://github.com/muesli/duf][duf]]. ~duf~ is a
  better replacement for ~df~ and should be more platform-agnostic than
  the latter. I also suspect this implementation will be faster than
  the one with ~df~, since there is very few string manipulation with
 ~duf~ compared to the implementations with ~df~.

  Default value: ~t~ if ~duf~ is found on the system, ~nil~ otherwise
- ~eshell-info-banner-duf-executable~ :: Path to your ~duf~ executable. If
 ~duf~ is not found by default by Emacs, you can override
 ~eshell-info-banner-use-duf~ with ~t~ and specify the path to ~duf~ with
  this custom variable.

  Default value: ~duf~
- ~eshell-info-banner-file-size-flavor~ :: This variable reflects the
  possible values passed to the function ~file-size-human-readable~. It
  can hold one of these three values:
  - ~nil~
  - ~si~
  - ~iec~
  Since the value ~iec~ generates longer file size prefixes, progress
  bars become slightly shorter. For more details on this option, see
  the documentation of ~file-size-human-readable~.

  Default value: ~nil~

** Faces
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.

* Advice for Windows users
Currently, the partitions detection is done only with the ~duf~
command-line utility. If you want a list of your partitions, I
strongly encourage you to install it on your system. See
[[https://github.com/muesli/duf#windows]].

* Contributing
See [[file:CONTRIBUTING.org]].

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