Projects

Project management for power users.

Installation

$ npm install -g projects

Quickstart

If the majority of your projects are subdirectories of one folder then the easiest way to get started is this (in my case my projects live underneath ~/p/):

$ npm install -g projects
$ echo "alias p=projects" >> ~/.bashrc
$ source ~/.bashrc
$ vim ~/.config/projects

# edit like so (note: this file will probably become JSON soon!)
[github]
username = beaugunderson

[projects]
directory = ~/p

$ p import ~/p/*
$ p github  # if you want to import metadata about your GitHub projects too

Try p remind, p git-status, p git-unpushed, and p not-git for examples of the time savings and management functionality I'm trying to enable.

Note that the color scheme currently assumes a dark background; if you find it hard to read try DISABLE_COLOR=true in your environment (a revamp of all colors is coming in the next version).

Shell completion

For autocompletion you can redirect projects --completion to a file in ~/.bash_completion (zsh is also supported) or use projects-modified.sh which also contains a fallback to _filedir so that you can still complete files and directories (I've opened an issue to get that improvement back into omelette, the completion library we use).

Commands

| Command | Description | |----------------|------------------------------------------------------------| | alias | output shell aliases | | clone | git clone a project | | each | run a command in each project directory | | edit | edit projects files | | gc | compact the projects database | | get | get an attribute for a project | | git-status | git status across all repositories | | git-unpushed | display repositories with unpushed commits | | github | fill your projects database with your GitHub repositories | | glob | glob across all project directories | | import | import a directory into projects | | info | show the JSON for a given project | | json-in | import your projects from plain JSON | | json-out | export your projects to plain JSON | | ls | list your porojects | | open | open a project's homepage | | not-git | list projects not in git | | query | query your projects | | remind | get a reminder of what you were last working on | | set | set an attribute to a given value for a project |

Writing your own commands

Projects is primarily a framework for making it easy to execute actions on one or more of your projects. For example, you could write a command to check the clean/dirty status of all of your checked out git repositories and list the dirty ones.

If you have an executable file in your PATH that starts with projects- then you can execute it underneath projects (and you're encouraged to share them with others!)

Examples

$ alias p=projects
$ cat ~/.config/projects
[github]
username = beaugunderson

[projects]
directory = ~/p

$ p info vim-scss-instead
{
  "name": "vim-scss-instead",
  "repository": "https://github.com/beaugunderson/vim-scss-instead.git",
  "language": "VimL",
  "role": "creator",
  "released": true,
  "status": "inactive"
}

$ p set vim-scss-instead homepage https://github.com/beaugunderson/vim-scss-instead
Set vim-scss-instead:homepage to "https://github.com/beaugunderson/vim-scss-instead"
$ p open vim-scss-instead # opens a web browser to the homepage URL
$ p clone vim-scss-instead
Cloning into '/Users/beau/p/vim-scss-instead'...
remote: Counting objects: 5, done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 5 (delta 0), reused 5 (delta 0)
Receiving objects: 100% (5/5), done.

$ p github
<snip>
Adding vim-scss-instead
Adding vim-human-dates
<snip>
Finished

$ p git-unpushed
node-helmsman: 6 commits ahead of origin
projects: 3 commits ahead of origin

You can also use something like fzf to make selecting a project via the CLI very easy:

contract-home() {
  sed "s|^$HOME|~|"
}

# cd to a project via fzf
pd() {
  cd $(projects ls -1 | \
    fzf --query="$1" | \
    xargs -I {} projects get --porcelain "{}" directory)
}

# open a project's URL via fzf
po() {
  open $(projects ls -1 | \
    fzf --query="$1" | \
    xargs -I {} projects get --porcelain "{}" homepage)
}

# edit a project file with $EDITOR via fzf
# note: requires gnu findutils
# on OS X you'll want to:
# `npm install -g ignore-pipe`
# `brew install findutils --with-default-names`
pe() {
  FILTERS='-type f '

  # filter out .git and node_modules with -prune to make the find much faster
  FILTERS+='-not -path \*/.git/\* -prune '
  FILTERS+='-not -path \*/node_modules/\* -prune '

  ADDITIONAL_FILTERS=$1

  if PROJECT_DIRECTORY=`projects resolve --relative .`; then
    FILE=$(bash -c "find $PROJECT_DIRECTORY \
      $FILTERS $ADDITIONAL_FILTERS 2> /dev/null" | \
        ignore-pipe | contract-home | fzf)
  else
    FILE=$(projects glob --expand | \
      xargs -I {} bash -c "find "{}" \
        $FILTERS $ADDITIONAL_FILTERS 2> /dev/null" | \
         ignore-pipe | contract-home | fzf)
  fi

  # bash -c needed to handle tilde expansion
  [ ! -z "$FILE" ] && bash -c "${EDITOR:-vim} "$FILE""
}

# edit a project file modified within in the last 7 days
per() {
  pe "-mtime -7"
}