eshell-info-banner.el

eshell-info-banner.el copied to clipboard

#+title: eshell-info-banner.el #+author: Lucien Cartier-Tilet #+email: [email protected] [[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]] [[https://github.com/Phundrak/eshell-info-banner.el/actions/workflows/workflow.yml][file:https://github.com/Phundrak/eshell-info-banner.el/actions/workflows/workflow.yml/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-filter-duplicate-partitions~ :: Try to filter out duplicate partitions. Two partitions are considered duplicate if they have the same size and amount of space used.

  Default value: ~nil~

• ~eshell-info-banner-exclude-partitions~ :: List of pattens to exclude from the partition list.

  Default value: ~nil~

• ~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, ~eshell-info-banner~ can only look for your partitions with ~duf~. 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][muesli/duf]].

• 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.