Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


incontext ("in this context") is a general-purpose context discovery and activation mechanism.

    incontext --init
    incontext [COMMAND [ARG...]]

Executes COMMAND with ARGs in an environment modified by a .context file in
this or an ancestor directory.

.context is expected to be an executable that does the work of modifying
the environment and executing its arguments.

If no COMMAND is specified, launch a shell with the modified environment


    --init			Create an example .context script in the current directory.

I found that the first thing I do when working on a project is

  • change to its directory in my terminal,
  • maybe activate a virtualenv or rbenv,
  • set a bunch of environment variables, including
  • modify the $PATH to include a bunch of project-specific scripts,
  • modify my $PS1 to remind me that this shell contains all these modifications,
  • and several other steps, depending on the project.

incontext allows me to stuff all of that into a short script, activate it from anywhere within my project directory structure, or run a single command in that environment without messing up my current environment.

Theory of operation

A context is the top-level directory of some project along with environment settings specific to that project. You are "within" that context when your current working directory is a subdirectory of that top-level project directory. Unfortunately, merely having your current directory set does not activate the project-specific environment settings.

incontext --init sets up an executable called .context in the root of that project directory with some helpful examples, where you may record your settings. Then, incontext uses findup to locate the nearest .context and Bernstein chaining to activate it.

Where you would normally run

python runserver

in an activated virtualenv to launch a Django development server, you may instead run

incontext python runserver

to run it in its virtualenv without activating that virtualenv for your own shell.

When not given a command, incontext defaults to launching a sub-shell. So you can apply all the modifcations you need for your project, then discard them all simply by exiting the subshell.


virtualenv, but also rubyenv

# TODO FIXME add tested examples to

a project needs environment settings

# TODO FIXME add tested examples to

deployment targets staging or production?

# TODO FIXME add tested examples to


datagrok/findup-sh: locates a given filename in the nearest ancestor directory.

Other tools like incontext

Several tools exist that perform context discovery and environment modification:

I prefer tools that do not override cd or run automatically everywhere. One reason is because my current directory might contain untrusted code or belong to a different user. kennethreitx/autoenv and direnv have an "authorized" mechanism to guard against that, though. Another reason is that explicit activation allows me to provide arguments, to e.g. target production instead of development for that invocation.

Some tools incur a lot of complexity by supporting the syntax of a limited set of different shells. incontext avoids this by modifying the environment and launching a new instance of the user's preferred shell or command. In this way, incontext is syntax-agnostic and will work with any shell. Its .context files default to bourne shell syntax, but this has no impact on the interactive shell users use. Finally, if desired, the .context file may be replaced by an executable written in any language, as long as it arranges to execute its arguments.

Some tools incur complexity by managing the setting and un-setting of environment variables in the user's current shell. Others eschew un-setting and allow environment settings to "leak" into other contexts when the user changes directories. incontext mostly avoids these problems by launching a subshell in a modified environment. Once the user exits the subshell, their original environment is restored.


  • git marks its context with a .git directory, and performs context discovery to allow git commands to work in any subdirectory of a git clone.
  • datagrok/subcommander is an older tool of mine from which incontext was derived. A future rewrite will delegate its context discovery features to incontext.

License: AGPL-3.0+ with additional permissions

This software is copyright 2017 Michael F. Lamb and released under the terms of the GNU Affero General Public License, version 3 (or, at your option, any later version,) with a grant of additional permission that allows you to apply any terms you wish to the output .context file. For details, see


a general-purpose context discovery and activation mechanism





No releases published


No packages published


You can’t perform that action at this time.