Tree @0.2 (Download .tar.gz)
shelf
Version 0.2. Subject to change in backwards-incompatible ways.
Cat's Eye Technologies' shelf is "a package installer which neither packages nor installs". It aims to be a replacement for toolshelf, implemented as a set of Bourne shell functions.
Quick Start
Download the file shelf.sh
and put it somewhere, say $HOME/shelf.sh
.
Or better, clone this repo as $HOME/.shelf
; then the file shelf.sh
will be at $HOME/.shelf/shelf.sh
, and you can pull the latest changes
with cd $HOME/.shelf && git pull origin master
.
Then add these four lines to the end of your shell startup script
(.bashrc
, .bash_profile
, or whatever):
. $HOME/.shelf/shelf.sh
export SHELF_FARMBASE=$HOME/.local # see below
export SHELF_PATH=$HOME/checkout1:$HOME/checkout2 # see below
shelf_init
Then start a new shell for it to take effect.
SHELF_FARMBASE
is the directory where the link farms will be created.
On some OSes $HOME/.local
has a similar purpose, so it can be used here
too. (Although note, the wisdom of doing that has not been fully vetted.)
SHELF_PATH
should be a colon-separated list of directories where you
will be keeping the source directories you wish to manage using shelf.
Usage
The following shell functions are defined by shelf.sh
and available for use:
-
shelf_link
DIR [DIR ...]Create links to the relevant files in DIR, in the appropriate link farm. One or more DIRs may be given.
-
shelf_unlink
DIR [DIR ...]Remove, from all link farms, any links to any files found in DIR. One or more DIRs may be given.
-
shelf_unlink_broken
Remove, from all link farms, any links that are broken.
-
shelf_build
DIR [DIR ...]Make a best-effort guess at how to build the sources in DIR, and try to build them using that method. One or more DIRs may be given.
-
shelf_test
DIR [DIR ...]Make a best-effort guess at how to run tests for the project in DIR, then run the tests using that method. One or more DIRs may be given.
-
shelf_pwd
NAMEPrint out the full path of the first directory on
SHELF_PATH
with name NAME, if one exists, else print nothing and return an error code 1. -
shelf_cd
NAMEChange directory to the first directory on
SHELF_PATH
with name NAME, if one exists, else display an error message and return an error code 1. -
shelf_which
NAMEEssentially the same as
which
but, if the found file is a symbolic link, display the filename that the link points to as well. -
shelf_dockgh
USER/PROJECTConvenience command which, given the user (or organization) and repository name of a repository on Github, clones that repository using
git
, then runsshelf_build
andshelf_link
on the clone's directory. This makes the most sense if the current directory is on theSHELF_PATH
, but no check is made. -
shelf_push
DEST DIR [DIR ...]Pushes changes from the project in DIR to the project of the same basename in DEST. Currently only supports git repos. Always pushes the changes to a branch in DEST whose name is the name of the current branch in DIR; if there is no such branch configured in DEST, an error occurs. DEST* should be a directory on the
SHELF_PATH
. -
shelf_fanout
DIRExecutes a
shelf_push
to every directory on theSHELF_PATH
that contains a project directory that has the same basename as DIR.
Catalog files
In the context of shelf, a catalog file is a text file with one entry per line.
Each entry consists of a directory name, optionally followed by an @
symbol
followed by a tag name.
Several commands operate on catalog files, which are usually supplied via standard input. Some of these commands ignore the tag names.
-
shelf_populate_from_distfiles
DIR < CATALOGGiven a directory DIR containing tarballs of the project listed in CATALOG, extract each of those tarballs to a directory of the same name in the current directory (assumed to be on
SHELF_PATH
.) -
shelf_populate_from_git
PREFIX < CATALOGFor each of the projects listed in CATALOG, prefix PREFIX to its name and attempt to clone that named object with
git
to a repository directory in the current directory (assumed to be onSHELF_PATH
.) -
shelf_cast
DIR < CATALOGWhen executed from a directory containing repositories listed in CATALOG, create a non-version-controlled directory in DIR from each of the listed repositories.
-
shelf_pin
< CATALOGWhen executed from a directory containing repositories listed in CATALOG, checks out each repository named in the catalog at the tag or branch given by its tag name.
-
shelf_unpin
< CATALOGWhen executed from a directory containing repositories listed in CATALOG, checks out each repository named in the catalog at the tip of its
master
branch.
Environment variables
-
SHELF_VERBOSE
If this environment variable is set to any non-empty value, the
shelf_*
functions will produce verbose messages on standard output about what they are doing, which can be useful for troubleshooting. -
SHELF_DRYRUN
If this environment variable is set to any non-empty value, the
shelf_*
functions will not make significant changes to the state of the filesystem (for example, running commands likeln
andrm
) and instead will only report that such changes would be made.
Commit History
@0.2
git clone https://git.catseye.tc/shelf/
- Merge pull request #1 from catseye/develop-0.2 Chris Pressey (commit: GitHub) 6 years ago
- Prep for release of version 0.2. Chris Pressey 6 years ago
- Add a few more items of documentation to the README. Chris Pressey 6 years ago
- Make _shelf_push() always push to the branch of the same name. Chris Pressey 6 years ago
- Rename shelf_cast_projection() to shelf_cast(), and document. Chris Pressey 6 years ago
- Document non-catalog commands; move catalog commands to a section. Chris Pressey 6 years ago
- Add shelf_fanout command. Chris Pressey 6 years ago
- Add shelf_push() command. Chris Pressey 6 years ago
- Add rudimentary shelf_dockgh command. Chris Pressey 6 years ago
- Fix bug in shelf_build; it and shelf_test do not exit immediately. Chris Pressey 6 years ago