API

Besides the default hook implementations which are available to you from your ellipsis.sh as hooks.<name>, there are a number of useful functions and variables which ellipsis exposes for you:

Index

Function/Variable Description
ellipsis.each Executes command for each installed package.
ellipsis.list_packages Lists all installed packages.
fs.backup Creates a backup of an existing file, ensuring you don't overwrite existing backups.
fs.file_exists Returns true if file exists.
fs.folder_empty Returns true if folder is empty.
fs.is_broken_symlink Returns true if file is a broken symlink.
fs.is_ellipsis_symlink Returns true if file is a symlink pointing to an ellipsis package.
fs.is_symlink Returns true if file is a symlink.
fs.link_rfile Symlinks a single file.
fs.link_file Symlinks a single file and prepends a dot.
fs.link_rfiles Symlinks all files in a given folder.
fs.link_files Symlinks all files in a given folder and prepends a dot.
fs.list_dirs Lists directories, useful for passing subdirectories to fs.link_files.
fs.list_symlinks Lists symlinks in a folder, defaulting to $ELLIPSIS_HOME.
fs.strip_dot Removes . prefix from files in a given directory.
fs.first_found Echo first file found from a list of files.
git.behind Prints number of commits local is behind remote.
git.clone Clones a Git repo, identical to git clone.
git.diffstat Displays git diff --stat.
git.status Displays git status -s.
git.has_changes Returns true if repository has changes.
git.has_untracked Returns true if repository has untracked files.
git.head Prints how far ahead a package is from origin.
git.is_behind Returns true if local repository is behind the remote.
git.last_updated Prints commit's relative last update time.
git.pull Identical to git pull.
git.push Identical to git push.
git.sha1 Prints last commit's sha1 using git rev-parse --short HEAD.
os.platform Returns one of cygwin, freebsd, linux, osx.
path.abs_path Return absolute path to $1.
path.is_path Simple heuristic to determine if $1 is a path.
path.relative_to_home Replaces $HOME with ~
path.expand Replaces ~ with $HOME
path.relative_to_packages Strips $ELLIPSIS_PACKAGES from path.
path.strip_dot Strip dot from hidden files/folders.
utils.cmd_exists Returns true if command exists.
utils.is_interactive Returns true if ellipsis is running in an interactive terminal.
utils.prompt Prompts user $1 message and returns true if YES or yes is input.
utils.run_installer Downloads and runs web-based shell script installers.
utils.version_compare Compare version strings. Usage: utils.version_compare "$Version1" ">=" "1.2.4".

ellipsis

ellipsis.each

Executes command for each installed package.

# example (Updates all packages)
ellipsis.each pkg.pull
ellipsis.list_packages

Lists all installed packages.

# example (Prints all package names)
for package in ellipsis.list_packages; do
    echo "$package"
done

fs

fs.backup

Creates a backup of an existing file, ensuring you don't overwrite existing backups.

# example (Makes a backup of 'file')
fs.backup file
fs.file_exists

Returns true if file exists.

# example (Echo message if 'file' exists)

if fs.file_exists file; then
    echo "The file 'file' exists"
fi
fs.folder_empty

Returns true if folder is empty.

# example (Echo message if 'folder' is empty)

if fs.folder_empty folder; then
    echo "The folder 'folder' is empty"
fi
fs.is_broken_symlink

Returns true if file is a broken symlink.

# example (Echo message if 'broken' is a broken symlink)

if fs.is_broken_symlink broken; then
    echo "The link 'broken' is a broken symlink"
fi
fs.is_ellipsis_symlink

Returns true if file is a symlink pointing to an ellipsis package.

# example (Echo message if 'link' links to ellipsis package)
if fs.is_ellipsis_symlink link; then
    echo "'link' is part of an ellipsis package"
fi
fs.is_symlink

Returns true if file is a symlink.

# example (Echo message if 'link' is a symlink)
if fs.is_symlink link; then
    echo "'link' is a symlink"
fi
fs.link_rfile

Symlinks a single file.

By default the file will be symlinked into $ELLIPSIS_HOME, but another location can be provided as a second parameter (including filename).

A backup will be made if the destination exists.

# example (Links 'file' to 'file' in $ELLIPSIS_HOME)
fs.link_rfile file

# example (Links 'file' to 'other_file' in $HOME)
fs.link_rfile file $HOME/other_file
fs.link_file

Symlinks a single file and prepends a dot if needed.

By default the file will be symlinked into $ELLIPSIS_HOME, but another location can be provided as a second parameter (including filename). If you provide a destination there won't be a dot prepended.

A backup will be made if the destination exists.

# example (Links 'file' to '.file' in $ELLIPSIS_HOME)
fs.link_file file

# example (Links 'file' to '.other_file' in $HOME)
fs.link_file file $HOME/.other_file
fs.link_rfiles

Calls fs.link_rfile for all files in a given directory.

The function accepts an optional second parameter to link to another directory then $ELLIPSIS_HOME.

# example (Links all files in 'dir' to $ELLIPSIS_HOME)
fs.link_files dir

# example (Links all files in 'dir' to $HOME/.config)
fs.link_files dir $HOME/.config
fs.link_files

Calls fs.link_file for all files in a given directory.

The function accepts an optional second parameter to link to another directory then $ELLIPSIS_HOME.

# example (Links all files in 'dir' to $ELLIPSIS_HOME, prepended with a dot)
fs.link_files dir

# example (Links all files in 'dir' to $HOME/.config, prepended with a dot)
fs.link_files dir $HOME/.config
fs.list_dirs

Lists directories, useful for passing subdirectories to fs.link_files.

# example ()
TODO
fs.list_symlinks

Lists symlinks in a folder, defaulting to $ELLIPSIS_HOME.

# example ()
TODO
fs.strip_dot

Removes . prefix from files in a given directory.

# example ()
TODO
fs.first_found

Echoes the first found file in a list. If no file was found return code will be 1.

fs.first_found 'file1' '/tmp/file2' "$HOME/file3" || echo "No file found"

git

git.ahead
Prints how far ahead a package is from origin.

# example ()
TODO
git.behind

Prints how far behead a package is from origin.

# example ()
TODO
git.clone

Clones a Git repo, identical to git clone.

# example ()
TODO
git.diffstat

Displays git diff --stat.

# example ()
TODO
git.status

Displays git status -s.

# example ()
TODO
git.has_changes

Returns true if repository has changes.

# example ()
TODO
git.has_untracked

Returns true if repository has untracked files.

# example ()
TODO
git.is_behind

Returns true if local is behind remote.

# example ()
TODO
git.last_updated

Prints commit's relative last update time.

# example ()
TODO
git.pull

Identical to git pull.

# example ()
TODO
git.push

Identical to git push.

# example ()
TODO
git.remote_branch

Prints name of remote branch.

# example ()
git.sha1

Prints last commit's sha1 using git rev-parse --short HEAD.

# example ()
TODO

os

os.platform

Returns one of cygwin, freebsd, linux, osx.

# example ()
TODO

path

path.abs_path

Return absolute path to $1.

# example ()
TODO
path.is_path

Simple heuristic to determine if $1 is a path.

# example ()
TODO
path.relative_to_home

Replaces $HOME with ~

# example ()
TODO
path.expand

Replaces ~ with $HOME

# example ()
TODO
path.relative_to_packages

Strips $ELLIPSIS_PACKAGES from path.

# example ()
TODO
path.strip_dot

Strip dot from hidden files/folders.

# example ()
TODO

Utils

utils.cmd_exists

Returns true if command exists.

# example ()
TODO
utils.is_interactive

Returns true if ellipsis is running in an interactive terminal.

# example ()
TODO
utils.prompt

Prompts user $1 message and returns true if YES or yes is input.

A default answer can be provided as a second argument. If there is no controlling terminal, this will be used instead of asking for input.

# example ()
TODO
utils.run_installer

Downloads and runs web-based shell script installers.

# example ()
TODO
utils.version_compare

Compare version strings. Usage: utils.version_compare "$Version1" ">=" "1.2.4".

# example ()
TODO