Who ever wants a documentation if there is a gif?

Installation

Now ash is available only from go get:

go get github.com/seletskiy/ash

After that, ash executable should be available for use.

Important note

ash is in a development phase, so it can crash unexpectedly.

However, all data you've entered will not be lost and will kept even in case of crash.

If you experience a crash, please, fill an issue and attach ash debug output (using --debug=2 cmd line flag) and review file caused a crash.

Why

There is a couple points:

• Stash web-interface is, well, slow; it will eventually slow down when your review grows in number of comments; your editor probably will not;
• Sometimes Stash can lost comments you're entered in spite of having "Drafts";
• You can unleash all power of your editor in reviewing code by highlighting syntax, inserting snippets and even running code;

Usage

Authorization

First of all, you need to specify login parameters for accessing Stash.

Easiest way to do that is to create config file named ~/.config/ash/ashrc and add following lines:

--user
  <your username here>

--pass
  <your password here>

Setting your editor

To make ash use editor of your choice you need either to export $EDITOR environment variable or just pass editor name to the -e flag.

You can use ashrc config too:

[... some other options goes here ...]

-e
 vim

Using vim

ashium

Best integration into vim on the present date available via https://github.com/seletskiy/ashium.

Full blown integration is not ready yet (PR please!), but it is useful to have following syntax highlights in ~/.vimrc (one probably wants to change color codes accordingly to colorscheme):

augroup syntax_hacks
    au!
    au FileType diff syn match DiffComment "^#.*"
    au FileType diff syn match DiffCommentIgnore "^###.*"
    au FileType diff call g:ApplySyntaxForDiffComments()
augroup end


fun! g:ApplySyntaxForDiffComments()
    if &background == 'light'
        hi DiffCommentIgnore ctermfg=249 ctermbg=none
        hi DiffComment ctermfg=16 ctermbg=254
    else
        hi DiffCommentIgnore ctermfg=249 ctermbg=none
        hi DiffComment ctermfg=15 ctermbg=237
    endif
endfun

ash.vim

Also, there is little bit deprecated, but still usable plugin ash.vim, see https://github.com/kovetskiy/ash.vim. This plugin has decent integration with ash.

Using sublime

Because of sublime uses client-server architecture by default, editor executable should be set in the way it will wait until review file editing is done.

You need to create wrapper and place it somewhere (preferably in the $PATH) /path/to/sublw:

#!/bin/sh

/path/to/sublime -w "${@}"

Then specify this shiny new executable (do not forget to chmod +x it) as ash editor:

-e
 /path/to/sublw

Using emacs

For simple integration emacs with ash see https://github.com/s-kostyaev/ash.el. But helm interface is now recommended.

Running ash

Now, using ash you can:

• list files in the review;
• review concrete file;
• see recent changes in overview mode;

Common usage of ash is:

ash inbox (only if --url given)
ash <pull request url> ls
ash <pull request url> review
ash <pull request url> review <file to review>

Reviewing

You can modify review file which will be opened in editor by:

• entering new line comments just after line you want to comment; you need to use # prefix for these kind of lines;
• modifying existing comments by just altering their text in file;
• deleting existing comments by just deleting their body;
• adding review-level/file-level comments by entering them outside of the diff context;
• replying to the existing comments by entering reply lines of text with some indentation after comment delimiter ---;

Tips and tricks

You can use shorthand syntax for accessing reviews without specifying full PR url.

There are two flags for that:

• --url which used to specify Stash host (e.g. http://stash.local/);
• --project which used to specify default project to search repo/pull-request;

So, you can add following to your ashrc:

--url
  http://<your stash hostname>/

--project
  mycoolproject

Now you can run ash like this:

ash myrepo/123 review
ash notsocoolproject/anotherrepo/456 review

State of things

• [x] fill todo list;
• [x] list files in review;
• [x] add, modify, delete line comments as well as review/file level comments;
• [x] make ash work in overview mode;
• [x] list reviews in project;
• [x] list inbox;
• [x] integrate ash with vim using Unite (PR is welcomed);
• [ ] integrate ash with sublime writing a plugin (PR is welcomed);
• [ ] be more tolerant to user mistakes (ash can crash sometime);
• [ ] wrap long lines in comments;