1diff --git a/plugins/mercurial/README.md b/plugins/mercurial/README.md
2new file mode 100644
3index 0000000000000000000000000000000000000000..89e1c17431b53ed996c9121baec858007c7de69a
4--- /dev/null
5+++ b/plugins/mercurial/README.md
6@@ -0,0 +1,64 @@
7+# Mercurial plugin
8+### Usage
9+Update .zshrc:
10+
11+1. Add name to the list of plugins, e.g. `plugins = (..., mercurial, ...)`
12+ (that is pretty obvious).
13+2. Change PROMPT variable of current theme to contain current folder mercurial repo info:
14+
15+ robbyrussel theme is used by default, so you need to modify PROMPT var
16+ from [this file](https://github.com/robbyrussell/oh-my-zsh/blob/master/themes/robbyrussell.zsh-theme)
17+ by adding `$(hg_prompt_info)` after `$(git_prompt_info)`, so currently it
18+ looks next:
19+
20+ ```diff
21+ - PROMPT='${ret_status}%{$fg_bold[green]%}%p %{$fg[cyan]%}%c %{$fg_bold[blue]%}$(git_prompt_info)%{$fg_bold[blue]%} % %{$reset_color%}'
22+ + PROMPT='${ret_status}%{$fg_bold[green]%}%p %{$fg[cyan]%}%c %{$fg_bold[blue]%}$(git_prompt_info)$(hg_prompt_info)%{$fg_bold[blue]%} % %{$reset_color%}'
23+ ```
24+
25+ and put modified var at the end of **.zshrc**.
26+3. Initialize additional vars used in plugin. So in short put next in **.zshrc**:
27+
28+ ```
29+ ZSH_THEME_HG_PROMPT_PREFIX="%{$fg_bold[magenta]%}hg:(%{$fg[red]%}"
30+ ZSH_THEME_HG_PROMPT_SUFFIX="%{$reset_color%}"
31+ ZSH_THEME_HG_PROMPT_DIRTY="%{$fg[magenta]%}) %{$fg[yellow]%}✗%{$reset_color%}"
32+ ZSH_THEME_HG_PROMPT_CLEAN="%{$fg[magenta]%})"
33+ ```
34+
35+### What's inside?
36+#### Adds handy aliases:
37+###### general
38+* `hgc` - `hg commit`
39+* `hgb` - `hg branch`
40+* `hgba` - `hg branches`
41+* `hgbk` - `hg bookmarks`
42+* `hgco` - `hg checkout`
43+* `hgd` - `hg diff`
44+* `hged` - `hg diffmerge`
45+
46+###### pull and update
47+* `hgi` - `hg incoming`
48+* `hgl` - `hg pull -u`
49+* `hglr` - `hg pull --rebase`
50+* `hgo` - `hg outgoing`
51+* `hgp` - `hg push`
52+* `hgs` - `hg status`
53+* `hgsl` - `hg log --limit 20 --template "{node|short} | {date|isodatesec} | {author|user}: {desc|strip|firstline}\n"`
54+
55+###### this is the 'git commit --amend' equivalent
56+* `hgca` - `hg qimport -r tip ; hg qrefresh -e ; hg qfinish tip`
57+
58+###### list unresolved files (since hg does not list unmerged files in the status command)
59+* `hgun` - `hg resolve --list`
60+
61+#### Displays repo branch and directory status in prompt
62+This is the same as git plugin does.
63+
64+**Note**: additional changes to **.zshrc** are required in order for this to
65+work.
66+
67+### Mantainers
68+[ptrv](https://github.com/ptrv) - original creator
69+
70+[oshybystyi](https://github.com/oshybystyi) - created this README and know how most of code works