rework commands overview

diff --git a/Commands b/Commands
index 82049d42a498d0ed3ce15172175a5051358d6e9f..04c5b61794d7360e672cd037e1d2c4ce53d2c927 100644 (file)
--- a/Commands
+++ b/Commands
@@ -1,3 +1,156 @@
+zpm: always a shell script, that way it can source config files and export environment
+variables for sub-programs
+
+Environment Variables
+---------------------
+
+Always set by the zpm wrapper.
+
+ZPMDB: path to local database
+ZPMPACKAGE: package name
+ZPMPKGVER: package version
+ZPMPKGREL: package release
+
+Package Selector
+----------------
+
+-p <package name> -V <package version> -R <package release>
+
+version and release are always the latest available if not specified
+for new packages, version defaults to 1.0, release to 1, but
+may also be taken from the environment
+
+command line over-rides environment, which over-rides defaults
+
+ZPM Wrapper Script
+------------------
+
+The primary executable is zpm, which is a shell script.  This script
+sources (if they exist) in order, /etc/zpm.conf ~/.zpmrc
+
+The script then parses its command line options up until the first non-option,
+export environment variables, and looks for a command of the form zpm-$1 which
+it then executes.  If the ZPMPATH is not set, it looks in PATH and if that is
+not set, in /sbin:/usr/libexec/zpm
+
+       -d <database file>
+       -f <database file> -- they're the same option, just different way of thinking about it
+
+Low Level Commands
+------------------
+
+Very low level commands to manipulate a database.  These can be used directly,
+but are primarily intended to be wrapped up in shell scripts.  Each of these
+should also have an equivalent in the C library API.  The zpm- prefix is omitted below.
+
+newpackage: add package metadata to a zpm database, creating the target file if
+needed.
+
+       -N require the target file to not exist (new)
+       -A require the target file to exist (add)
+       -P packager string, should be an email, use ZPMPACKAGER environment
+
+addtopackage: add a file to a package
+       
+       -C <n> number of leading components to strip
+       -P <path prefix> prefix to strip
+       -H hard coded path, regardless of the source 
+       -T track only, don't import the contents
+       -c flag as configuration file
+       -t <tag list> comma or space separated tags on file
+
+       zpm -f foobar-1.0-1.zpm addtopackage /usr/bin/foo /usr/bin/bar
+       zpm addtopackage foobar-1.1-3.zpm /usr/bin/foo /usr/bin/bar
+       zpm add -f foobar-1.1-3.zpm -p bar /usr/bin/bar
+
+       need to think about the syntax here, but best to just write something,
+       then change it later
+       
+extract: pull file content to disk
+       $1 is hash or hash prefix if unique, $2 is target path
+
+       As per install(8)
+       -m mode
+       -o owner
+       -g group
+
+       -D don't create leading directories
+
+list: list package contents
+
+       -F <format> %p path %m mode %o owner %g group %h hash
+       -N don't append a newline to format
+       -0 append a null byte to the format
+
+       default format is '%h %m %o %g %p'
+
+show: list packages
+       maybe reverse list and show
+
+drop: delete a package
+
+delete: remove a file from a package
+
+adjust: adjust file metadata
+       
+Higher Level Commands
+---------------------
+
+install: install a package to the local system
+       search repositories known in the local db for a matching package
+remove: remove a package
+update: update a package
+
+       -D dry-run, just show what might be done
+
+export: create a standalone package file from a repo/localdb
+
+json: dump the metadata of a repo as json
+
+Repositories
+------------
+
+A repository is just a collection of packages.  All in one DB, or perhaps
+mark an external file location for package contents.
+
+Repository Definition is just a url.
+Has a priority.  Can require trusted signer.  Can require confirmation.
+Install/Search will ask on tied priorities.  Warn on lower priorities.
+
+Fetch a repo by getting the json file, or by getting a stripped down DB file.
+
+repo import: adds repository information from the json file
+repo drop <url or name>
+repo add <url> [name]
+repo refresh: update repository info
+
+repo command needs to know how to get metadata from local files
+for http[s] urls, path given should return either json or sqlite db, responsibility
+of repo to make this work
+
+Building Packages
+-----------------
+
+build: builds a package file
+       -S read paths from stdin
+
+       Reads PKGBUILD in the current directory
+       -b build script path instead of PKGBUILD
+
+Other Commands
+--------------
+
+absorb: pull in the content of a file.  note the mtime if it's a config file, possibly
+keeping multiple versions
+
+truncate: drop the content of a file
+
+status:
+       investigate the status of a repo, reporting things like failed installs or removes,
+       file conflicts, anything else
+
+integritycheck: compare the stored hashes with the hashes on disk
+
 note:
        add a note file, - from stdin, list if none
 
@@ -7,19 +160,9 @@ edit:
 ack:
        acknowledge a note file
 
-build:
-       build a package from source
-       - take file names on stdin and build package from them
-       - <name> repackage an installed package
-
-install:
-       install a package, - <name> for from a file
-
-remove:
-       remove a package
-
-db:
-       edit package databases used for finding packages
+diff:
+       compare two versions of a package, show what would be done
+       or different
 
 info:
        get information on a package
@@ -30,3 +173,4 @@ track:
 add: add to a repository/database
 
 clean: clean a repository/database
+