Great Teeming Workspaces

This handles workspaces for multiple versions of multiple projects.  You can
create, update, enter and leave workspaces easily, and each <project, version>
combo has at most one local origin that syncs to and from upstream.  All other
workspaces update from the local origin.

Layout is as follows:

${GTWS_ORIGIN}/<project>/<repo>[/<version>]
${GTWS_BASE_SRCDIR}/<project>/<version>/<workspacename>/{<repo>[,<repo>...]}

Each level in the source tree (plus the homedir for globals) can have a .gtwsrc
file in it that maintains settings and bash code relevant to that level.  Each
more specific level overrides higher levels.

- Setup Overview
	- Checkout gtws
		git clone https://github.com/dang/gtws.git
		- The location of gtws is called GTWS_LOC
	- Set up your ${HOME}/.gtwsrc
		- Should include GTWS_ORIGIN, optionally GTWS_SETPROMPT
	- Add the repo directory to your path
		export PATH="${PATH}:/path/to/gtws
	- Profit

- Configuration
	Configuration is via cascading .gtwsrc files.  The real path down from
	the root is walked, and each .gtwsrc file found is sourced in turn.
	More specific files override less specific ones.  There are sample
	versions of all the .gtwsrc files in ${GTWS_LOC}/examples

	These settings should be in your top level ~/.gtws/.gtwsrc:

	- GTWS_BASE_SRCDIR
		- This is the base of all the projects source trees.  Defaults to $HOME/src
	- GTWS_ORIGIN
		- This sets the location of the origin git trees.  Defaults to $HOME/origin
	- GTWS_SETPROMPT
		- This is optional.  If set, the shell prompt will be changed
		  to have the workspace name in it.
	- GTWS_DEFAULT_PROJECT
		- This is the project used when no project is given or known.
		  If this is not given, projects must be specified on the
		  command line.
	- GTWS_DEFAULT_PROJECT_VERSION
		- Default version to check out.  Defaults to "master"

	These settings should be at the project level of each project:

	- GTWS_PROJECT
		- Name (and base directory) of the project in question.
	- gtws_project_clone
		- This is a function used to clone a specific version if a
		  project.  If it is not defined, then it is assumed that the
		  origin for the project contains a single directory per
		  version, and that contains a set of git repo to clone.
	- gtws_project_setup
		- This optional function is called after all cloning is done,
		  and allows any addidional setup necessary for the project,
		  such as setting up workspaces in an IDE.

	These settings should be set at the project version level:

	- GTWS_PROJECT_VERSION
		- This is the version of the project.  It's used to pull from
		  the origin correctly.  In git, this is likely a branch name.

	
	These things can go anywhere in the tree, and can be overridden
	multiple times if that makes sense:

	GTWS_PATH_EXTRA
		- Extra path elements to be added to the path inside the workspace
	GTWS_FILES_EXTRA
		- Extra files not under version control that should be copied
		  into each checkout in the workspace.  This is things like
		  .git/info/exclude and each file is relative to the base of
		  it's repo.


- Origin dirs
	GTWS_ORIGIN (in most scripts) points to the pristine git checkouts to
	pull from and push to.

	- Layout of ${GTWS_ORIGIN}
		- /<project>
			- This is the base for repos for a project.
			- If gtws_project_clone is given, this can have any
			  layout desired.
			- If gtws_project_clone is *not* given, this must
			  contain a subdirectory named "git" that contains a
			  set of bare git repos to clone.
			- It can optionally contain a directory named
			  "submodule" that contains mirrors of all the
			  submodule repos from the project.
		- These directories can be created using the "gtws-mirror"
		  command.  See the examples.

- Workflow
	Suppose you have a project "Foo" that has a an upstream repository at
	"github.com/foo/foo.git".  This repo has a submodule named "bar" with
	an upstream at "github.com/bar/bar.git".  The Foo project does
	development in the master branch, and uses stable version branches.

	The first thing you need to do to use gtws with foo is to set up the
	directory structure.  These examples all assume you are using the
	default directory structure.

	- Set up your top level .gtwsrc:
		cp ${GTWS_LOC}/examples/gtwsrc.top ~/.gtwsrc
		- Edit ~/.gtwsrc and change as necessary
	- Create top level directories:
		mkdir -p ~/origin ~/src
	- Create and setup the project directory:
		mkdir -p ~/src/foo
		cp ${GTWS_LOC}/examples/gtwsrc.project ~/src/foo/.gtwsrc
		- Edit ~/src/foo/.gtwsrc and change as necessary
	- Create and setup the master version directory:
		mkdir -p ~/src/foo/master
		cp ${GTWS_LOC}/examples/gtwsrc.version ~/src/foo/master/.gtwsrc
		- Edit ~/src/foo/master/.gtwsrc and change as necessary
	- Go to the version directory, and create a temporary workspace to set
	  up the mirrors:
		mkdir -p ~/src/foo/master/tmp
		cd ~/src/foo/master/tmp
		git clone --recurse-submodules git://github.com/foo/foo.git
		cd foo
		gtws-mirror -o ~/origin -p foo
		- This will create ~/origin/foo/git/foo.git and ~/origin/foo/submodule/bar.git
		- Future clones will clone from these origins, rather than from upstream.
		- This "workspace" can be deleted now.

	At this point, work can be done on the master branch of foo.  Suppose
	you want to fix a bug named "bug1234".  You can create a workspace for
	this work, to keep it isolated from anything else you're working on,
	and then work within this workspace.

	- Go to the version directory, and create a new workspace:
		cd ~/src/foo/master
		mkws bug1234
		- This creates bug1234/ and inside it checks out foo (and it's
		  submodule bar), and makes build/foo for building it.
	- Enter the workspace.  This can be done two ways:
		cd ~/src/foo/master/bug1234
		startws
		- or
		cd ~/src/foo/master/
		startws bug1234
		- This starts a subshell within the bug1234 workspace.  This
		  shell has the GTWS environment, plus any environment you set
		  up in your stacked .gtwsrc files.  It also adds the base of
		  the workspace to your CD path, so you can cd into relative
		  paths from that base.
		- At this point, you can do work on bug1234, build it, test it,
		  and commit your changes.  When you're ready to push to
		  upstream, push like this:
		cd foo
		wspush
		- "wspush" will push the branch associated with your workspace
		  first to your local orgin, and then to the upstream.
		- If upstream changes. you can sync your local checkout using:
		git sync
		- This envokes the "git-sync" script in gtws, which will update
		  your checkout from the local origin.  To update the local
		  origin, use:
		git sync -o
		- This will update your local origin and submodules mirrors,
		  then use those to update your checkout.  git-sync has other
		  nice features.
		- When your done using the workspace, just exit the shell:
		exit
		- You can re-enter the workspace at any time, and have multiple
		  shells in the same workspace at the same time.
	- When your done with a workspace, you can remove it using the "rmws"
	  command, or just remove it's directory tree.
	- There is a script named "tmws" that enters a workspace within tmux,
	  creating a set of windows/panes that are fairly specific to my
	  workflow.  Feel free to modify it to suite your needs.