TERMINAL ANIMATIONS

Demo

Display animations as you wait for running commands in your terminal.

Table of Contents (Click to expand)

• Demo
• Overview
• Why Use This?
• Installation
• Download the Latest Release
• Run Makefile
• Add Alias (Optional but Recommended)
• Special for Bash Users
• Advantages of Sourcing animate.sh
• Usage
• Examples
• Command Output
• Creating a New Animation
  • Create a New Script File
  • Define the Animation Frames
  • Use the Animation
• License

Overview

animate.sh is a light-weight Bash script that adds a touch of interactivity and fun to terminal commands. It enhances the user experience in terminal environments by providing visual feedback during command execution.

Why Use This?

• Lightweight and easy to use.
• No external dependencies required.
• Works with multiple shells i.e bash, zsh, fish, etc.
• Multiple animation styles and customizable frames.
• Adjustable animation speed, prefixes, and suffixes.
• Logs command output for debugging and auditing.
• Graceful error handling with detailed logs.

Installation

To install and setup animate.sh for any shell just:

1. Download the Latest Release

   Visit the Releases page, download the latest release, and extract it:

   tar -xzf terminal-animations-v*.tar.gz
      cd terminal-animations-v*
   

2. Run Makefile

   make install
   

3. Add Alias (Optional but Recommended)

   For convenience, add an alias to your shell’s configuration file (e.g. .zshrc) with your default options:

   # You can add such a line to your shell's configuration
   alias ::='animate.sh <your-default-options>'
   

4. Special for Bash/Zsh Users

   Bash/Zsh users can also source animations.sh (not animate.sh) in their .bashrc file. This will automatically add a command named :: to the shell’s environment.

   cp animations.sh $HOME/.animations.sh &&
       echo 'source ~/.animations.sh' >> ~/.bashrc
   

   Restart your terminal to use the command ::.

   Advantages of Sourcing animate.sh

   • Allows use of aliased commands with the program.
   • Automatically adds the :: command to the shell environment.

Usage

animate.sh [OPTION] [--] COMMAND [ARGS...]

See man animate.sh or animate.sh --help for more information.

Examples

1. Customise Animation

   animate.sh -a spinner -p 'Sleeping ' sleep 5
   

2. Customise prefix

   # <name> will be replaced with the command name
   animate.sh -a bar -p 'Downloading file with <name> ' wget https://example.com/largefile.zip
   

3. Customise Animation Frames

   animate.sh -f '⠁,⠂,⠄,⡀,⢀,⠠,⠐,⠈' -i 0.1 -- tar -czf archive.tar.gz /path/to/directory
   

Command Output

Command output is sent to logs_directory/command_name.log.

Creating a New Animation

The animations directory contains predefined animations but you can also create your own animations by following these steps:

1. Create a New Script File

   Create a new file in the animations directory ending with .sh. This will be the name of the animation i.e. classic.sh for an animation named classic.

   touch ~/.local/share/animations/classic.sh
   

2. Define the Animation Frames

   Inside the script, define an array named __animations__frames containing the animation frames. i.e

   # Name: classic
   __animations__frames=('-' '\' '|' '/')
   

3. Use the Animation

   Use the -a option with the animation name (excluding the .sh) to use your new animation i.e

   # exclude the .sh in the name
   animate.sh -a classic sleep 5
   

License

    Copyright (C) 2025  Jore

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <https://www.gnu.org/licenses/>.