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 (regular) file into $ELLIPSIS_HOME.
fs.link_file Symlinks a single (dot) file into $ELLIPSIS_HOME.
fs.link_files Symlinks all files in given folder into $ELLIPSIS_HOME.
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.source_first Sources (and echo's) first file found.
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 (regular) file into $ELLIPSIS_HOME.

By default the file will be symlinked into $HOME, but another location can be provided as a second parameter.

# example (Links 'file' to 'file' in $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 (dot) file into $ELLIPSIS_HOME. A dot will be prepended if needed.

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

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

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

fs.link_files

Symlinks all files in given folder as dotfiles into $ELLIPSIS_HOME.

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

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

Sources the first found file in a list. The sourced file will be echoed. If no file found return code will be 1.

fs.source_first '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