ash
ash copied to clipboard
Atlassian Stash (Bitbucket) reviews in editor
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
withvim
usingUnite
(PR is welcomed); - [ ] integrate
ash
withsublime
writing a plugin (PR is welcomed); - [ ] be more tolerant to user mistakes (
ash
can crash sometime); - [ ] wrap long lines in comments;