From f2fc48c8990d26fc11d15a75004ca0f92261dee1 Mon Sep 17 00:00:00 2001 From: qadzek <84473512+qadzek@users.noreply.github.com> Date: Sat, 16 Mar 2024 22:56:55 +0100 Subject: [PATCH 1/4] Clarify creating a custom module --- README.md | 2 +- custom/README.md | 71 ++++++++++++++++++++++++++++++++--------------- custom/example.sh | 15 ++++++---- 3 files changed, 59 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 29ef238f..74bd9250 100644 --- a/README.md +++ b/README.md @@ -431,7 +431,7 @@ set -g @catppuccin_status_modules_right "... uptime ..." It is possible to add a new custom module or overwrite any of the existing modules. -Look into custom/README.md for more details. +Look into [custom/README.md](https://github.com/catppuccin/tmux/blob/main/README.md) for more details. Any file added to the custom folder will be preserved when updating catppuccin. diff --git a/custom/README.md b/custom/README.md index b4a11cb8..b168a6ce 100644 --- a/custom/README.md +++ b/custom/README.md @@ -1,43 +1,70 @@ # User defined modules -## Description +## Description This folder is used to store user defined modules. You can use this folder to add a new module or override any existing module. -To override an existing module, make sure you use the same name for your module as the module you want to override. -You can also override the window module for current and default window. +To override an existing module, make sure that you use the same name for your module as the module you want to override. +You can also override the window module for the current and default window. ## Create a new module -Use the [Module template](#module-template) (or example.sh) as a starting point when creating a new module. -Save the new module under this folder using the module name as the file name and .sh as the extension. -Update the status module list with your module. -```sh -set -g @catppuccin_status_modules_right "... ..." +You can create a custom module by following these steps. +Note that changes will only take effect after reloading your Tmux configuration by executing `tmux source-file ~/.tmux.conf`. -``` +### New file + +Create a new file in `~/.tmux/plugins/tmux/custom/.sh`, to store the custom module. The extension has to be `.sh`. Making this file executable is not necessary. + +### File content + +Copy the following template to that file. Make sure to replace every instance of `` by the name you chose as filename. -## Module template ```sh -show_() { # save this module in a file with the name .sh - local index=$1 # this variable is used by the module loader in order to know the position of this module - local icon="$(get_tmux_option "@catppuccin__icon" "")" - local color="$(get_tmux_option "@catppuccin__color" "")" - local text="$(get_tmux_option "@catppuccin__text" "")" +show_() { # This function name must match the module name! + local index icon color text module + + index=$1 # This variable is used internally by the module loader in order to know the position of this module + icon="$( get_tmux_option "@catppuccin__icon" "" )" + color="$( get_tmux_option "@catppuccin__color" "$thm_orange" )" + text="$( get_tmux_option "@catppuccin__text" "hello world" )" - local module=$( build_status_module "$index" "$icon" "$color" "$text" ) + module=$( build_status_module "$index" "$icon" "$color" "$text" ) echo "$module" } ``` -## Configure custom modules path +### Status module list -You can configure a custom path for your modules by setting the `@catppuccin_custom_plugin_dir` option. -```sh -set -g @catppuccin_custom_plugin_dir "" +Add the custom module to the list of modules in `.tmux.conf` + +```tmux +set -g @catppuccin_status_modules_right "... ..." ``` -To use the output of a command, use e.g. `local text="$(get_tmux_option "@catppuccin_test_text" "#(date +%T)")"`. +### Customization -To use the output of a script, use e.g. `local text="$(get_tmux_option "@catppuccin_test_text" "#($HOME/my_script.sh)")"`. +Change the icon to one from [Nerd Fonts](https://www.nerdfonts.com/cheat-sheet). +Change the color to one of the [official colors](https://github.com/catppuccin/tmux/blob/main/catppuccin-macchiato.tmuxtheme), for instance `"$thm_orange"`, or to a hexadecimal color like `"#00ff00"`. + +The text to display can either be: + +- A static text, e.g. `"hello world"`. +- The output of a command, e.g. `"#( date +%T )"`. +- The output of a script, e.g. `"#( $HOME/my_script.sh )"` . Any script will do, e.g. a Bash or Python script that prints some text, but ensure that it is executable `chmod u+x my_script.sh`. +- An existing Tmux plugin, e.g. `" #{forecast} "` for the [Tmux Weather plugin](https://github.com/aaronpowell/tmux-weather). + +Note that the icon and the color can be generated dynamically as well, by having a Bash script e.g. `echo` a hexadecimal color. + +To modify how often the modules are updated, add the following to `.tmux.conf`: + +```tmux +set -g status-interval +``` + +To configure a custom path for your modules, set this option: + +```tmux +set -g @catppuccin_custom_plugin_dir "" +``` diff --git a/custom/example.sh b/custom/example.sh index 613caa75..8a6d21c8 100644 --- a/custom/example.sh +++ b/custom/example.sh @@ -1,10 +1,13 @@ -show_example() { - local index=$1 - local icon="$(get_tmux_option "@catppuccin_test_icon" "󰙨")" - local color="$(get_tmux_option "@catppuccin_test_color" "$thm_blue")" - local text="$(get_tmux_option "@catppuccin_test_text" "It works!")" +show_test() { # This function name must match the module name! + local index icon color text module - local module=$( build_status_module "$index" "$icon" "$color" "$text" ) + index=$1 # This variable is used internally by the module loader in order to know the position of this module + icon="$( get_tmux_option "@catppuccin_test_icon" "" )" + color="$( get_tmux_option "@catppuccin_test_color" "$thm_orange" )" + text="$( get_tmux_option "@catppuccin_test_text" "hello world" )" + + module=$( build_status_module "$index" "$icon" "$color" "$text" ) echo "$module" } + From e0d6f8492234115d7dd7d179ee9c687113782534 Mon Sep 17 00:00:00 2001 From: qadzek <84473512+qadzek@users.noreply.github.com> Date: Sun, 17 Mar 2024 14:27:11 +0100 Subject: [PATCH 2/4] Fix path Co-authored-by: Hamothy <58985301+sgoudham@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 74bd9250..f14b54f9 100644 --- a/README.md +++ b/README.md @@ -431,7 +431,7 @@ set -g @catppuccin_status_modules_right "... uptime ..." It is possible to add a new custom module or overwrite any of the existing modules. -Look into [custom/README.md](https://github.com/catppuccin/tmux/blob/main/README.md) for more details. +For further details, see the documentation in [custom/README.md](custom/README.md) Any file added to the custom folder will be preserved when updating catppuccin. From 0c6d2d353d737760fd392f3cda2562bed737e41b Mon Sep 17 00:00:00 2001 From: qadzek <84473512+qadzek@users.noreply.github.com> Date: Sun, 17 Mar 2024 14:52:08 +0100 Subject: [PATCH 3/4] Fix formatting and mention required plugins --- custom/README.md | 47 ++++++++++++++++++++++++++--------------------- custom/example.sh | 3 +++ 2 files changed, 29 insertions(+), 21 deletions(-) diff --git a/custom/README.md b/custom/README.md index b168a6ce..ee226f00 100644 --- a/custom/README.md +++ b/custom/README.md @@ -2,29 +2,35 @@ ## Description -This folder is used to store user defined modules. -You can use this folder to add a new module or override any existing module. -To override an existing module, make sure that you use the same name for your module as the module you want to override. -You can also override the window module for the current and default window. +This folder is used to store user defined modules. You can use this folder to +add a new module or override any existing module. To override an existing +module, make sure that you use the same name for your module as the module you +want to override. You can also override the window module for the current and +default window. -## Create a new module +## Creating A New Module -You can create a custom module by following these steps. -Note that changes will only take effect after reloading your Tmux configuration by executing `tmux source-file ~/.tmux.conf`. +> [!NOTE] +> Changes will only be applied after reloading your Tmux configuration by executing `tmux source-file ~/.tmux.conf`. -### New file +You can create a custom module by following the steps outlined below. This can be something you create entirely by yourself or integrating an existing Tmux plugin. -Create a new file in `~/.tmux/plugins/tmux/custom/.sh`, to store the custom module. The extension has to be `.sh`. Making this file executable is not necessary. +1. Create a new file in `~/.tmux/plugins/tmux/custom/.sh` to store the custom module. -### File content +- The file **must** end in `.sh` +- The file **does not** need to be set as executable. -Copy the following template to that file. Make sure to replace every instance of `` by the name you chose as filename. +2. Copy the following template to this new file. Make sure to replace every instance of `` by the name you chose as filename. + +```bash +# If this module depends on an external Tmux plugin, say so in a comment. +# E.g.: Requires https://github.com/aaronpowell/tmux-weather -```sh show_() { # This function name must match the module name! local index icon color text module - index=$1 # This variable is used internally by the module loader in order to know the position of this module + index=$1 # This variable is used internally by the module loader in order to know the position of this module + icon="$( get_tmux_option "@catppuccin__icon" "" )" color="$( get_tmux_option "@catppuccin__color" "$thm_orange" )" text="$( get_tmux_option "@catppuccin__text" "hello world" )" @@ -35,27 +41,26 @@ show_() { # This function name must match the module name! } ``` -### Status module list - -Add the custom module to the list of modules in `.tmux.conf` +3. Add the custom module to the list of modules in `.tmux.conf` -```tmux +```bash set -g @catppuccin_status_modules_right "... ..." ``` -### Customization +## Customization Change the icon to one from [Nerd Fonts](https://www.nerdfonts.com/cheat-sheet). -Change the color to one of the [official colors](https://github.com/catppuccin/tmux/blob/main/catppuccin-macchiato.tmuxtheme), for instance `"$thm_orange"`, or to a hexadecimal color like `"#00ff00"`. + +Change the color to one of the [official colors](../catppuccin-macchiato.tmuxtheme), for instance `"$thm_cyan"`, or to a hexadecimal color like `"#00ff00"`. The text to display can either be: - A static text, e.g. `"hello world"`. - The output of a command, e.g. `"#( date +%T )"`. -- The output of a script, e.g. `"#( $HOME/my_script.sh )"` . Any script will do, e.g. a Bash or Python script that prints some text, but ensure that it is executable `chmod u+x my_script.sh`. +- The output of a script, e.g. `"#( $HOME/my_script.sh )"` . Any script will do, e.g. a Bash or Python script that prints some text, but ensure that it is executable: `chmod u+x my_script.sh`. - An existing Tmux plugin, e.g. `" #{forecast} "` for the [Tmux Weather plugin](https://github.com/aaronpowell/tmux-weather). -Note that the icon and the color can be generated dynamically as well, by having a Bash script e.g. `echo` a hexadecimal color. +Note that the icon and the color can be generated dynamically as well, for instance by having a Bash script `echo` a hexadecimal color. To modify how often the modules are updated, add the following to `.tmux.conf`: diff --git a/custom/example.sh b/custom/example.sh index 8a6d21c8..3b093678 100644 --- a/custom/example.sh +++ b/custom/example.sh @@ -1,3 +1,6 @@ +# If this module depends on an external Tmux plugin, say so in a comment. +# E.g.: Requires https://github.com/aaronpowell/tmux-weather + show_test() { # This function name must match the module name! local index icon color text module From 13ada5d4391f4ad33ce7130b3f8291175339f9d0 Mon Sep 17 00:00:00 2001 From: sgoudham Date: Sun, 17 Mar 2024 15:19:48 +0000 Subject: [PATCH 4/4] docs: indentation & small tweaks --- custom/README.md | 41 +++++++++++++++++++---------------------- 1 file changed, 19 insertions(+), 22 deletions(-) diff --git a/custom/README.md b/custom/README.md index ee226f00..65f66bf3 100644 --- a/custom/README.md +++ b/custom/README.md @@ -1,6 +1,4 @@ -# User defined modules - -## Description +# User Defined Modules This folder is used to store user defined modules. You can use this folder to add a new module or override any existing module. To override an existing @@ -16,36 +14,35 @@ default window. You can create a custom module by following the steps outlined below. This can be something you create entirely by yourself or integrating an existing Tmux plugin. 1. Create a new file in `~/.tmux/plugins/tmux/custom/.sh` to store the custom module. - -- The file **must** end in `.sh` -- The file **does not** need to be set as executable. + - The file **must** end in `.sh` + - The file **does not** need to be set as executable. 2. Copy the following template to this new file. Make sure to replace every instance of `` by the name you chose as filename. -```bash -# If this module depends on an external Tmux plugin, say so in a comment. -# E.g.: Requires https://github.com/aaronpowell/tmux-weather + ```bash + # If this module depends on an external Tmux plugin, say so in a comment. + # E.g.: Requires https://github.com/aaronpowell/tmux-weather -show_() { # This function name must match the module name! - local index icon color text module + show_() { # This function name must match the module name! + local index icon color text module - index=$1 # This variable is used internally by the module loader in order to know the position of this module + index=$1 # This variable is used internally by the module loader in order to know the position of this module - icon="$( get_tmux_option "@catppuccin__icon" "" )" - color="$( get_tmux_option "@catppuccin__color" "$thm_orange" )" - text="$( get_tmux_option "@catppuccin__text" "hello world" )" + icon="$( get_tmux_option "@catppuccin__icon" "" )" + color="$( get_tmux_option "@catppuccin__color" "$thm_orange" )" + text="$( get_tmux_option "@catppuccin__text" "hello world" )" - module=$( build_status_module "$index" "$icon" "$color" "$text" ) + module=$( build_status_module "$index" "$icon" "$color" "$text" ) - echo "$module" -} -``` + echo "$module" + } + ``` 3. Add the custom module to the list of modules in `.tmux.conf` -```bash -set -g @catppuccin_status_modules_right "... ..." -``` + ```bash + set -g @catppuccin_status_modules_right "... ..." + ``` ## Customization