pin 0.1rc1

pin is a generic project management tool for the commandline.

Downloads ↓

pin
======

**pin** is a plugin-based command-line utility that helps you manage your software development projects. At it's core, it is a registry of where your projects reside on your file-system. Registering your project with **pin** lets you use utilize the various plugins. Since **pin** is generic, what this means exactly is based on what your project is and what plugins you have installed.

### Installation

    $ sudo pip install pin

### Usage

To use **pin** you will need to source it's shell-script which is installed under the name **pin.sh**:

    $ source pin.sh

The **pin** command will now be available to you. To see the core pin commands you can use the **help** command:

    $ pin help
    usage: pin [-v]

    optional arguments:
      -v, --version  show program's version number and exit

    Available commands for /home/dlacewell/dev/mine/pin:
    destroy  - Destroy and unregister the project from pin.
         go  - Teleport to a specific project.
       help  - This help information.
       init  - Initialize pin in the current directory.
    $

Lets try out **pin init** in a new directory:

    $ mkdir /tmp/testing
    $ cd /tmp/testing
    $ pin init
    Creating .pin directory structure...
    pin project initialized in: /tmp/testing
    $

**pin** has created a project directory located at */tmp/testing/.pin/* **Generally, commands that operate upon your project can be used *anywhere* below the project's root directory**. **pin** doesn't do much on it's own but plugins can add new functionality to existing commands or new commands all together. Let's go ahead and install the *pin-venv* plugins to give **pin** the ability to work with *VirtualEnv*.

    $ sudo pip install pinvenv
    ...
    $ rm -fdr .pin/
    $ pin init --venv
    Creating .pin directory structure...
    Creating virtualenv...
    pin project initialized in: /tmp/testing
    $ ls .pin/env
    bin include lib
    $

### Core Commands

**pin init** : Initializes the .pin directory and registers the path with ~/.pinconf/registry.yml

**pin destroy** : Deletes the project's .pin directory and unregisters the project path. Only works from inside a project tree.

**pin go <project-name>** : Teleports to the project root if a name is provided. If no name is provided a menu will be presented.

**pin help** : Lists all pin commands including any provided by installed plugins.

### Plugins

Plugins to extend pin's core functionality can be found at the [Pin Cushion](https://github.com/dustinlacewell/pin/wiki/Pin-Cushion)


### Writing Plugins

Plugins for **pin** are packaged as Namespace packages. Ensure that your plugin package resembles the following structure:

    yourpackage/
      setup.py
      requirements.tx
      README
      pin/
        __init__.py
        plugins/
          __init__.py
          yourpackage.py

To make your package namespaced you will need to add the following lines to each of the two **__init__.py** files:

    import pkg_resources
    pkg_resources.declare_namespace(__name__)

The two plugin-classes that you can register with pip are **commands** and **hooks**. Before covering those specifically, let's review some notable API available for plugins to use:

### Utility API

 * **util.path_has_project(path)** : Determine if the supplied path contains the pin project-directory.

 * **util.get_project_root(path)** : Find the root project directory for the path, if there is one.

 * **util.get_settings_filename()** : Get the absolute path to the pin settings YAML file

 * **util.get_registry_filename()** : Get the absolute path to the pin registry YAML file


### Writing Commands

The base command class is **command.Pincommand**. Your command will be a subclass that you register with **command.register(cls)**. There are a number of methods that you can override to define the behavior of your command. At minimum your class needs to define a class-attribute '**command**' which is the name of your command. Let's write a simple command called '*check*' the determines if the current-working-directory is inside of a pin project:

    class CheckCommand(command.PinCommand):
        command = 'check'

Just to illustrate the proper way to handle arguments

• Author: Dustin Lacewell
• Home Page: https://github.com/dustinlacewell/pin
• Provides pin
• Package Index Owner: dustinlacewell
• DOAP record: pin-0.1rc1.xml