[!NOTE]
+> If you used v1 before and interested to adpt to v2 use this [Migration Guide from v1 to v2][docs-migration-guide-from-v1-to-v2].
+
### Install manually
> [!TIP]
@@ -55,26 +67,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 +119,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
@@ -98,6 +131,10 @@ set -g @tmux-gruvbox-left-status-a '#S' # tmux's session name
This section is customizable for user, and by default contains current date.
+> [!TIP]
+> Some user may have problem with displaying dates in desired format, if this
+> case for you try using double percent `%%`
+
```bash
# set date in US notation
set -g @tmux-gruvbox-right-status-x '%m/%d/%Y' # e.g.: 01/31/2024
@@ -121,7 +158,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 +214,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..7d19e70
--- /dev/null
+++ b/docs/migration-guide-from-v1-to-v2.md
@@ -0,0 +1,91 @@
+# Migration guide from v1 to v2
+
+Hello there!
+
+I am so happy to see you here and being interested in using 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 change
+
+| v1 | v2 | description |
+| :-----------------: | :--------: | ----------------------------------------------------------------------- |
+| `dark` | `dark256` | |
+| `light` | `light256` | |
+| `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 v1 theme `light` & `dark` has been simply renamed and `256` postfix
+has been added to indicate used palette.
+
+> [!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 automaticaly 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 `