phundrak/eshell-info-banner.el
1
0
Fork 0
Code Issues Pull Requests Releases Activity
b7f2bfc013
eshell-info-banner.el/README.org
Lucien Cartier-Tilet fcc88df86a
Add CI with Github Actions 
Check for compatibility with all version of Emacs since Emacs 25.1

Add Cask file for managing dependencies in CI

Add badge in README for CI
2022-05-31 11:40:22 +02:00

203 lines
9.2 KiB
Org Mode
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

#+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]]
[[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-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.
View Git Blame Copy Permalink