watson (mirror) is a tool for creating and tracking bug reports, issues, and internal notes in code.
It is avaliable in three flavors, watson-ruby, watson-python and watson-perl

watson-python has been tested with Python 2.7.5 (on Mac OS 10.9 Mavericks) watson-python requires no additional dependancies.

[todo] - sort this section out. watson-python is avaliable via PyPI (link).
You can either download it directly from PyPI using

pip watson-python

or you can clone this repo and install with setuptools.

git clone https://github.com/mleonard87/watson-python.get .
cd watson-python
python setup.py install

For a quick idea of how to use watson, check out the app demo! (mirror)
See below for a description of what all the command line arguments do.

If you see something missing from the list please either file an issue or
submit a pull request (comment parsing happens in watson/paser.py)

• C / C++
• Objective C
• C#
• Java
• Javascript
• PHP
• Go
• Scala
• Erlang
• Haskell
• Bash / Zsh
• Ruby
• Perl
• Python
• Coffeescript
• Clojure [todo] - Implement Oracle PL/SQL parser.
• Oracle PL/SQL (.pks, .pkb, .trg, .fnc, .prc) [todo] - Implement XML parser.
• XML

Usage: watson [OPTION]...
Running watson with no arguments will parse with settings in RC file
If no RC file exists, default RC file will be created

   -c, --context-lines          number of lines of context to provide with posted issue
   -d, --dirs                   list of directories to search in
   -f, --files                  list of files to search in
   -h, --help                   print help
   -i, --ignore                 list of files, directories, or types to ignore
   -p, --parse-depth            depth to recursively parse directories
   -r, --remote                 list / create tokens for Bitbucket/Github
   -s, --show                   whether to show [all, clean, dirty] files
   -t, --tags                   list of tags to search for
   -u, --update                 update remote repos with current issues
   -v, --version                print watson version and info

Any number of files, tags, dirs, and ignores can be listed after flag
Ignored files should be space separated
To use *.filetype identifier, encapsulate in "" to avoid shell substitutions

Report bugs to: watson@goosecode.com
watson home page: <http://goosecode.com/projects/watson>
[goosecode] labs | 2012-2013

This parameter specifies how many lines of context watson should include when posting issues to remote repos.
When this parameter is set from the command line, the .watsonrc config file is written with the value; the command line option effectively sets the default value for this feature in the current directory.
The default value is set to 15 (and can be found in the lib/watson/command.rb file).

This parameter specifies which directories watson should parse through.
It should be followed by a space separated list of directories that should be parsed.
If watson is run without this parameter, the current directory is parsed.

This parameter specifies which files watson should parse through.
It should be followed by a space separated list of files that should be parsed.

This parameter displays the list of avaliable options for watson.

This parameter specifies which files and directories watson should ignore when parsing.
It should be followed by a space separated list of files and/or directories to be ignored.
This parameter should be used as an opposite to -d/-f, when there are more files that should be parsed in a directory than should be ignored.

This parameter specifies how deep watson should recursively parse directories.
The 'depth' is defined as how many levels deep from the top-most specified directory to parse.
If individual directories are passed with the -d (--dirs) flag, each will be parsed PARSE_DEPTH layers, regardless of their depth from the current directory.
If watson is run without this parameter, the parsing depth is unlimited and will search through all subdirectories found.

This parameter is used to both list currently established remotes as well as setup new ones.
If passed without any options, the currently established remotes will be listed.
If passed with a github or bitbucket argument, watson will proceed to ask some questions to set up the corresponding remote.

This parameter is used to specify which types of files and entries are shown when watson is run.
If passed with the clean argument, only files that watson did NOT find issues in will be displayed.
If passed with the dirty argument, only files that watson DID find issues in will be displayed.
If passed with the all argument, watson will display all files, regardless of their issue status.
The default behavior of watson is the all option.

This parameter is used to specify which tags watson should look for when parsing.
The tag currently supports any regular character and number combination, no special (!@#$...) characters.

This parameter is used to update remote repos with new issues.
watson does not post new issues by default therefore this parameter is required to push up to GitHub/Bitbucket.
watson does pull issue status by default, therefore you will always be notified of resolved issues on GitHub/Bitbucket.

This parameter displays the current version of watson you are running.

watson supports an RC file that allows for reusing commong settings without repeating command line arguments every time.

The .watsonrc is placed in every directory that watson is run from as opposed to a unified file (in ~/.watsonrc for example). The thinking behind this is that each project may have a different set of folders to ignore, directories to search through, and tags to look for.
For example, a C/C++ project might want to look in src/ and ignore obj/ whereas a Ruby project might want to look in lib/ and ignore assets/.

The .watsonrc file is fairly straightforward...
[dirs] - This is a newline separated list of directories to look in while parsing.

[tags] - This is a newline separated list of tags to look for while parsing.

[ignore] - This is a newline separated list of files / folders to ignore while parsing.
This supports wildcard type selecting by providing .filename (no * required)

[context_depth] - This value determines how many lines of context should be grabbed for each issue when posting to a remote.

[(github/bitbucket)] - If a remote is established, the API key for the corresponding remote is stored here.
Currently, OAuth has yet to be implemented for Bitbucket so the Bitbucket username is stored here.

[(github/bitbucket)_repo] - The repo name / path is stored here.

The remote related .watsonrc options shouldn't need to be edited manually, as they are automatically populated when the -r, --remote setup is called.

Special thanks to @nhmood for creating watson (ruby and perl versions).

• Why Python?
  I really wanted to use watson at work and due to various restirctions Ruby and Perl wern't ideal. I already used Python so it seemed like a good idea to port it.