[!NOTE]
+> If you used v1 before and interested to adapt to v2 use this [Migration Guide from v1 to v2][docs-migration-guide-from-v1-to-v2].
+
### Install manually
> [!TIP]
@@ -55,26 +65,47 @@ Hit `prefix + I` to fetch the plugin and source it. Your Tmux should be updated
```bash
# ~/.tmux.conf
+
run ~/projects/tmux-gruvbox/tmux-gruvbox.tmux
# set desired options...
- set -g @tmux-gruvbox 'dark' # or light
+ set -g @tmux-gruvbox 'dark' # or 'dark256', 'light', 'light256'
```
## Configuration options
+
+
+
+
+
+
### Theme
- default value: `dark256`
-- available themes:
- - `dark` ([preview][imgur-img-gruvbox-dark-16bit-1x])
- - `light` ([preview][imgur-img-gruvbox-light-16bit-1x])
- - `dark256` ([preview][imgur-img-gruvbox-dark256-1x])
- - `light256` ([preview][imgur-img-gruvbox-light256-1x])
+
+| Theme name | Color palette | Preview link |
+| :--------- | :------------ | :-------------------------------------------------------------------- |
+| `dark` | 16-bit colors | preview |
+| `light` | 16-bit colors | preview |
+| `dark256` | 256 colors | preview |
+| `light256` | 256 colors | preview |
```bash
set -g @tmux-gruvbox 'dark' # dark256, light, light256
```
+> [!TIP]
+> Each terminal emulator can behave bit differently regarding displaying colors.
+> If you have some problems see
+> [True Color (24-bit) and italics with alacritty + tmux + vim (neovim)][github-gist-andersevenrud-alacritty-tmux-vim-truecolor]
+> where there is great wisdom how to adjust terminal, especially when used
+> alacritty and tmux.
+
### Transparent status-bar
- default value: `'false'`
@@ -86,7 +117,7 @@ set -g @tmux-gruvbox-statusbar-alpha 'true'
### Left Status (Section A)
-- default value: `'#S'`
+- default value: `'#S'` (session name)
```bash
set -g @tmux-gruvbox-left-status-a '#S' # tmux's session name
@@ -108,6 +139,10 @@ set -g @tmux-gruvbox-right-status-x '%m/%d/%Y' # e.g.: 01/31/2024
set -g @tmux-gruvbox-right-status-x '%d.%m.%Y' # e.g.: 30.01.2024
```
+> [!TIP]
+> Some user may have problem with displaying dates in desired format, if this
+> case for you try using double percent `%%`
+
### Right Status (Section Y)
- default value: `'%H:%M'`
@@ -121,7 +156,7 @@ set -g @tmux-gruvbox-right-status-y '%I:%M %p' # 09:54 PM
### Right Status (Section Z)
-- default value: `'#h'`
+- default value: `'#h'` (hostname)
This section is customizable for user, and by default contains hostname.
@@ -177,18 +212,20 @@ To keep the files clean we use few program to help us achieve it:
GPLv3 - Maciej Sypień
-[github-tmux]: https://github.com/tmux/tmux
+[docs-migration-guide-from-v1-to-v2]: ./docs/migration-guide-from-v1-to-v2.md
+[github-alacritty]: https://github.com/alacritty/alacritty
+[github-gist-andersevenrud-alacritty-tmux-vim-truecolor]: https://gist.github.com/andersevenrud/015e61af2fd264371032763d4ed965b6
[github-grovbox]: https://github.com/morhetz/gruvbox
[github-hack]: https://github.com/chrissimpkins/Hack
[github-nerd-fonts]: https://github.com/ryanoasis/nerd-fonts
-[github-alacritty]: https://github.com/alacritty/alacritty
+[github-seebi-tmux-color-solarized]: https://github.com/seebi/tmux-colors-solarized
+[github-tmux]: https://github.com/tmux/tmux
[github-tpm]: https://github.com/tmux-plugins/tpm
-[tmux-color-solarized]: https://github.com/seebi/tmux-colors-solarized
-[pexcel-1]: https://www.pexels.com/photo/urban-photo-of-an-alley-2411688/
-[pexcel-2]: https://www.pexels.com/photo/lights-hanging-above-the-alley-in-a-city-at-night-27044195/
-[imgur-img-gruvbox-dark-light-comparision-1x]: https://i.imgur.com/uGyGwlC.png
-[imgur-img-gruvbox-dark-light-comparision-0.5x]: https://i.imgur.com/p6lUnzb.png
[imgur-img-gruvbox-dark-16bit-1x]: https://i.imgur.com/ae88LQI.png
+[imgur-img-gruvbox-dark-light-comparision-0.5x]: https://i.imgur.com/p6lUnzb.png
+[imgur-img-gruvbox-dark-light-comparision-1x]: https://i.imgur.com/uGyGwlC.png
[imgur-img-gruvbox-dark256-1x]: https://i.imgur.com/kzQTTCa.png
[imgur-img-gruvbox-light-16bit-1x]: https://i.imgur.com/fvpdRjg.png
[imgur-img-gruvbox-light256-1x]: https://i.imgur.com/tQsl6LA.png
+[pexcel-1]: https://www.pexels.com/photo/urban-photo-of-an-alley-2411688/
+[pexcel-2]: https://www.pexels.com/photo/lights-hanging-above-the-alley-in-a-city-at-night-27044195/
diff --git a/docs/migration-guide-from-v1-to-v2.md b/docs/migration-guide-from-v1-to-v2.md
new file mode 100644
index 0000000..0c69639
--- /dev/null
+++ b/docs/migration-guide-from-v1-to-v2.md
@@ -0,0 +1,73 @@
+# Migration guide from v1 to v2
+
+Hello there!
+
+I am so happy to see you here and are interested in using the new version of tmux-gruvbox theme.
+
+I really try to do all my best giving you new, interesting features that you probably always wanted to have.
+
+In here I also wanted to thank you all people involved in contributing to this theme 🙏🙇. Especially for adding all suggestions, or reporting problems if they occurred - this helped a lot!
+
+## What's new?
+
+There are couple of great things ahead:
+
+- new themes supporting 16-bit color palette
+- new fully customizable spaces A, X, Y, Z for your disposal
+- support for transparency (experimental)
+- and many more
+
+See what's new in [CHANGELOG][docs-changelog].
+
+## Breaking changes
+
+I planned to have best possible user experience between migrating from v1 and v2, therefore tried to build new changes this way to keep the breaking changes as low as possible. This was not ideal, although I believe for many this would not require many changes and for some none.
+
+### Theme names changes
+
+| v1 | v2 | description |
+| :-----------------: | :--------: | ----------------------------------------------------------------------- |
+| `dark` | `dark256` | 256-colors theme |
+| `light` | `light256` | 256-colors theme |
+| `dark-transparent` | ∅ | set `dark` or `dark256` theme and add `@tmux-gruvbox-statusbar-alpha` |
+| `light-transparent` | ∅ | set `light` or `light256` theme and add `@tmux-gruvbox-statusbar-alpha` |
+
+In v2 we've introduced a 16-bit color themes that should give the users more happiness utilizing a greater amount of supported colors (full gruvbox palette).
+
+Therefore in v2 themes `light` & `dark` has been simply renamed and `256` postfix has been added to indicate used palette. In v2 `light` & `dark` themes will be refering to 16-bit versions.
+
+> [!NOTE]
+> While implementing 16-bit colors I realized that many users (including me) had problems with setting up correct the color interpretation in their workspace to support multiple colors.
+>
+> Here is the page [True Color (24-bit) and italics with alacritty + tmux + vim (neovim)][github-gist-andersevenrud-alacritty-tmux-vim-truecolor] where I found great wisdom how to adjust my terminal, especially when used alacritty, tmux & neovim.
+
+### Fallback theme name
+
+| v1 | v2 |
+| :----: | :-------: |
+| `dark` | `dark256` |
+
+Continuing topic of introducing 16-bit colors, we have make slight change in fallback theme name. We love idea adding new colors to our theme, although during those changes we cannot forget about users whose terminals might not support more then basic 256 colors. Therefore the fallback theme name also has to be adapted and in v2 it's `dark256`.
+
+## FAQ
+
+### Plugin not upgrading automatically with tmux update
+
+Error ([source](https://github.com/egel/tmux-gruvbox/issues/21#issuecomment-2373794273)):
+
+```
+"tmux-gruvbox" update fail
+ | fatal: couldn't find remote ref refs/heads/master
+```
+
+Solution:
+
+We recently migrate from `master` to `main` as the primary branch, therefore tmux plugin manager using old reference to master and it's not possible to pull.
+
+The simplest way would be to:
+
+1. remove the plugin `rm -rf ~/.tmux/plugins/tmux-gruvbox`
+2. and reinstall it again via tpm key-binding `