129 lines
5.3 KiB
Org Mode
129 lines
5.3 KiB
Org Mode
#+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!
|
||
|
||
* Table of Contents :TOC_2_gh:
|
||
- [[#introduction][Introduction]]
|
||
- [[#installation][Installation]]
|
||
- [[#customizing][Customizing]]
|
||
- [[#my-computer-doesnt-have-a-battery-will-this-still-work][My computer doesn’t have a battery, will this still work?]]
|
||
- [[#contributing][Contributing]]
|
||
- [[#license][License]]
|
||
|
||
* 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-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~
|
||
|
||
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.
|
||
|
||
* 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 [[file:LICENSE.md][LICENSE.md]].
|