| Name | tmux-conf JSON |
| Version |
0.16.6
JSON |
| download |
| home_page | |
| Summary | Generates version checked tmux conf |
| upload_time | 2023-08-08 21:58:42 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | |
| keywords |
tmux
automation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Tmux-Conf
This is meant for users running tmux on multiple hosts, not always
running the same version of tmux.
This generates tmux config files where version checks can be used, so
that features not working on a given version can be handled gracefully.
Either replaced by something suitable for that version, or just skipped.
This gets rid of annoying startup error messages for features not being
available on the running version and failure to parse the rest of the config.
The optional [plugin](docs/PLUGINS.md) handling is also automated in the
sense that plugins not usable on the given version of tmux are skipped.
If any plugins are defined they will be auto-installed on first run.
This in combination with hostname matching makes it easy to adopt a
given environment based both on tmux version available, and what
features are relevant for that host. Managing a music player is
probably not all that meaningful on a remote cloud host :)
The generation of a tmux.conf takes only a fraction of a second, so I
use some scripts to regenerate the config each time I start tmux on
that system.
This will make new features automatically activated as soon as that node
gets a tmux version supporting it, without having to give it any
thought.
I sometimes also bind keys for functionality not available on a given
version of tmux to display a message like "Popup scratchpad session
needs 3.2". So that I never have to wonder why nothing happened if I
attempt something not supported on that system.
## Availability
Simplest way to install is using `pip install tmux-conf`
## Suggested approach
Drop your current tmux.conf inside a content() method, wrapping stuff
to be written to the conf file inside write() statements. If you
experience version glitches, wrap those items inside vers_ok()
statements.
If so desired also migrating your current plugins setup into plugin_XX
methods. Thus they will also be version checked.
## General features
- First scans for plugins available for this version and creates a list
of those plugins. This list can be used when defining the status line
to only include parts relevant for plugins being used.
- Plugins are version checked, incompatible plugins are ignored.
- If tpm is used it will be installed if not present on startup.
- All version compatible plugins are installed on startup, regrdless
if tpm or manual plugin handling is used.
- Check if the current tmux matches a version limit with vers_ok()
to decide if something should be included.
- Conf file defines $TMUX_BIN, pointing to the actual tmux/tmate bin
used to run this environment, and can be used in scripts and plugins
to use the right binary.
- Built in script handling for tasks that would just be painful to
mangle into tmux commands with all the escaping that entails.
Scripts will either be embedded or stored in separate files.
- Filters out -N bind notes automatically if current tmux doesn't
support the feature, so just leave them in if you prefer to use them.
- Lazy adopting, initially just drop in your current config.
If at some point you experience a version complaining about something,
just wrap that inside a vers_ok() clause and its done. No need to
over-analyze your entire setup unless you experiment with older
versions of tmux.
- Supports config inheritance, you can have your basic config,
and then subclass it and define things like what plugins are being
used on a per node basis.
- Platform dependent plugins can be auto filtered
## Conditional status bar snippets
Blindly including plugin related code in the status bar can lead to
issues, especially if the status bar snippet calls an external script.
If the script is not present, it will trigger an error, and if the
script is present, but that plugin isn't intended to be used at the
moment, it can lead to unintended side effects.
Recommended approach is to first check what plugins are currently used
by calling self.plugins.found().
This returns the names of all defined plugins matching the current tmux
version and can be used to only include relevant items in the
status bar.
```python
w = self.write
used_plugins = self.plugins.found()
if "tmux-packet-loss" in used_plugins:
sb_right = "#{packet_loss}" + sb_right
if "tmux-prefix-highlight" in used_plugins:
sb_right += "#{prefix_highlight}"
w(f"set -g status-right '{sb_right}'")
```
## Version Testing
Combining this with using for example asdf to build multiple versions
of tmux, this is a convenient way to test plugins you are working on
for version compatibility.
And if so desired a test bench to get your plugins to work with older
tmux versions.
## My usage case
In my case i have set it up with some basic plugins I normally always
expect to be available, then for my laptop I have added ones that
would only make sense on a local system, like that music player.
A few very limited systems have more resource heavy standard plugins
disabled automatically.
The end result is that I have one single tmux config I use on all
systems. You can check it out at
[jaclu/my_tmux_conf](https://github.com/jaclu/my_tmux_conf)
I don't have to think about what version of tmux is available, my
config takes care of adopting. When I start using a feature from a
new version of tmux, I can just put it in my standard config with a
version check preventing it from being used on older tmuxes.
As versions gets updated the new feature automatically becomes more
widely available.
## Version checks
Parameter for calls to vers_ok() is flexible, can be either int, float or
string. In most cases a float is sufficient, like 2.8
Since some versions include a trailing letter, like 3.3a, then a string
param would be needed. If version is given as int, it will be appended
with .0
## Example snippets
If you notice version glitches, start wrapping those inside conditions:
```python
if self.vers_ok(3.2):
w("set -s extended-keys on")
#
# Not needed for all terminal apps, but since it doesn't hurt,
# it makes sense to always include it
#
w("set -as terminal-features 'xterm*:extkeys'")
```
A more complex example, with multiple version considerations.
Since there is no real fall back option doing something similar for
older versions, if the running tmux is to old, a notice that the
feature is not available is bound to the key.
```python
scrpad_key = "O" # P being taken, this is pOpup :)
if self.vers_ok(3.2):
display_popup = "display-popup -h 70% -w 70% -E "
if self.vers_ok(3.3):
display_popup += "-T " '"#[align=centre] pOpup Scratchpad Session " '
w(
f'bind -N "pOpup scratchpad session" {scrpad_key} '
f'{display_popup} "$TMUX_BIN -u new-session -ADs scratch"'
)
else:
w(
f'bind -N "pOpup not available warning" {scrpad_key} '
f'display "pOpup scratchpad session needs 3.2"'
)
```
## Scripting
This package handles using regular scripts for more complex tasks
that would just be painful to wrap inside tmux notation.
Such scripts can either be saved as embedded in the tmux conf file or
as external files in scripts/ next to plugins/
See [docs/scripting.md](docs/scripting.md) for more info.
Raw data
{
"_id": null,
"home_page": "",
"name": "tmux-conf",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "tmux,automation",
"author": "",
"author_email": "Jacob Lundqvist <Jacob.Lundqvist@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4f/eb/7b97b4a52de8aad73d042e4615651545a254758b63335c086cedafb79aea/tmux_conf-0.16.6.tar.gz",
"platform": null,
"description": "# Tmux-Conf\n\nThis is meant for users running tmux on multiple hosts, not always\nrunning the same version of tmux.\n\nThis generates tmux config files where version checks can be used, so\nthat features not working on a given version can be handled gracefully.\nEither replaced by something suitable for that version, or just skipped.\n\nThis gets rid of annoying startup error messages for features not being\navailable on the running version and failure to parse the rest of the config.\n\nThe optional [plugin](docs/PLUGINS.md) handling is also automated in the\nsense that plugins not usable on the given version of tmux are skipped.\nIf any plugins are defined they will be auto-installed on first run.\n\nThis in combination with hostname matching makes it easy to adopt a\ngiven environment based both on tmux version available, and what\nfeatures are relevant for that host. Managing a music player is\nprobably not all that meaningful on a remote cloud host :)\n\nThe generation of a tmux.conf takes only a fraction of a second, so I\nuse some scripts to regenerate the config each time I start tmux on\nthat system.\nThis will make new features automatically activated as soon as that node\ngets a tmux version supporting it, without having to give it any\nthought.\nI sometimes also bind keys for functionality not available on a given\nversion of tmux to display a message like \"Popup scratchpad session\nneeds 3.2\". So that I never have to wonder why nothing happened if I\nattempt something not supported on that system.\n\n## Availability\n\nSimplest way to install is using `pip install tmux-conf`\n\n## Suggested approach\n\nDrop your current tmux.conf inside a content() method, wrapping stuff\nto be written to the conf file inside write() statements. If you\nexperience version glitches, wrap those items inside vers_ok()\nstatements.\n\nIf so desired also migrating your current plugins setup into plugin_XX\nmethods. Thus they will also be version checked.\n\n## General features\n\n- First scans for plugins available for this version and creates a list\n of those plugins. This list can be used when defining the status line\n to only include parts relevant for plugins being used.\n- Plugins are version checked, incompatible plugins are ignored.\n- If tpm is used it will be installed if not present on startup.\n- All version compatible plugins are installed on startup, regrdless\n if tpm or manual plugin handling is used.\n- Check if the current tmux matches a version limit with vers_ok()\n to decide if something should be included.\n- Conf file defines $TMUX_BIN, pointing to the actual tmux/tmate bin\n used to run this environment, and can be used in scripts and plugins\n to use the right binary.\n- Built in script handling for tasks that would just be painful to\n mangle into tmux commands with all the escaping that entails.\n Scripts will either be embedded or stored in separate files.\n- Filters out -N bind notes automatically if current tmux doesn't\n support the feature, so just leave them in if you prefer to use them.\n- Lazy adopting, initially just drop in your current config.\n If at some point you experience a version complaining about something,\n just wrap that inside a vers_ok() clause and its done. No need to\n over-analyze your entire setup unless you experiment with older\n versions of tmux.\n- Supports config inheritance, you can have your basic config,\n and then subclass it and define things like what plugins are being\n used on a per node basis.\n- Platform dependent plugins can be auto filtered\n\n## Conditional status bar snippets\n\nBlindly including plugin related code in the status bar can lead to\nissues, especially if the status bar snippet calls an external script.\nIf the script is not present, it will trigger an error, and if the\nscript is present, but that plugin isn't intended to be used at the\nmoment, it can lead to unintended side effects.\n\nRecommended approach is to first check what plugins are currently used\nby calling self.plugins.found().\nThis returns the names of all defined plugins matching the current tmux\nversion and can be used to only include relevant items in the\nstatus bar.\n\n```python\n\n w = self.write\n used_plugins = self.plugins.found()\n\n if \"tmux-packet-loss\" in used_plugins:\n sb_right = \"#{packet_loss}\" + sb_right\n\n if \"tmux-prefix-highlight\" in used_plugins:\n sb_right += \"#{prefix_highlight}\"\n\n w(f\"set -g status-right '{sb_right}'\")\n\n```\n\n## Version Testing\n\nCombining this with using for example asdf to build multiple versions\nof tmux, this is a convenient way to test plugins you are working on\nfor version compatibility.\nAnd if so desired a test bench to get your plugins to work with older\ntmux versions.\n\n## My usage case\n\nIn my case i have set it up with some basic plugins I normally always\nexpect to be available, then for my laptop I have added ones that\nwould only make sense on a local system, like that music player.\nA few very limited systems have more resource heavy standard plugins\ndisabled automatically.\n\nThe end result is that I have one single tmux config I use on all\nsystems. You can check it out at\n[jaclu/my_tmux_conf](https://github.com/jaclu/my_tmux_conf)\nI don't have to think about what version of tmux is available, my\nconfig takes care of adopting. When I start using a feature from a\nnew version of tmux, I can just put it in my standard config with a\nversion check preventing it from being used on older tmuxes.\nAs versions gets updated the new feature automatically becomes more\nwidely available.\n\n## Version checks\n\nParameter for calls to vers_ok() is flexible, can be either int, float or\nstring. In most cases a float is sufficient, like 2.8\n\nSince some versions include a trailing letter, like 3.3a, then a string\nparam would be needed. If version is given as int, it will be appended\nwith .0\n\n## Example snippets\n\nIf you notice version glitches, start wrapping those inside conditions:\n\n```python\n\n if self.vers_ok(3.2):\n w(\"set -s extended-keys on\")\n #\n # Not needed for all terminal apps, but since it doesn't hurt,\n # it makes sense to always include it\n #\n w(\"set -as terminal-features 'xterm*:extkeys'\")\n\n```\n\nA more complex example, with multiple version considerations.\nSince there is no real fall back option doing something similar for\nolder versions, if the running tmux is to old, a notice that the\nfeature is not available is bound to the key.\n\n```python\n\n scrpad_key = \"O\" # P being taken, this is pOpup :)\n if self.vers_ok(3.2):\n display_popup = \"display-popup -h 70% -w 70% -E \"\n if self.vers_ok(3.3):\n display_popup += \"-T \" '\"#[align=centre] pOpup Scratchpad Session \" '\n w(\n f'bind -N \"pOpup scratchpad session\" {scrpad_key} '\n f'{display_popup} \"$TMUX_BIN -u new-session -ADs scratch\"'\n )\n else:\n w(\n f'bind -N \"pOpup not available warning\" {scrpad_key} '\n f'display \"pOpup scratchpad session needs 3.2\"'\n )\n\n```\n\n## Scripting\n\nThis package handles using regular scripts for more complex tasks\nthat would just be painful to wrap inside tmux notation.\n\nSuch scripts can either be saved as embedded in the tmux conf file or\nas external files in scripts/ next to plugins/\n\nSee [docs/scripting.md](docs/scripting.md) for more info.\n",
"bugtrack_url": null,
"license": "",
"summary": "Generates version checked tmux conf",
"version": "0.16.6",
"project_urls": {
"Bug Tracker": "https://github.com/jaclu/tmux-conf/issues",
"Homepage": "https://github.com/jaclu/tmux-conf",
"documentation": "https://github.com/jaclu/tmux-conf",
"repository": "https://github.com/jaclu/tmux-conf"
},
"split_keywords": [
"tmux",
"automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cedc3e24cd19c33538299a9a8e45c1426bd786b6012904b1152920c88033ef0c",
"md5": "5bf0cc7486fba8cf968681801a22032e",
"sha256": "41391af1eb19d8de40d6e5d2563b9c238e4f439e8ad865b513caa050ae197a16"
},
"downloads": -1,
"filename": "tmux_conf-0.16.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5bf0cc7486fba8cf968681801a22032e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 24132,
"upload_time": "2023-08-08T21:58:40",
"upload_time_iso_8601": "2023-08-08T21:58:40.853572Z",
"url": "https://files.pythonhosted.org/packages/ce/dc/3e24cd19c33538299a9a8e45c1426bd786b6012904b1152920c88033ef0c/tmux_conf-0.16.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4feb7b97b4a52de8aad73d042e4615651545a254758b63335c086cedafb79aea",
"md5": "88dff17a7dfaf3291973abe2e7ba93d5",
"sha256": "0f4f0f20cb2589b75e5079ba80a291f84d99cdf381590e57a639f42f2a219569"
},
"downloads": -1,
"filename": "tmux_conf-0.16.6.tar.gz",
"has_sig": false,
"md5_digest": "88dff17a7dfaf3291973abe2e7ba93d5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 31533,
"upload_time": "2023-08-08T21:58:42",
"upload_time_iso_8601": "2023-08-08T21:58:42.811241Z",
"url": "https://files.pythonhosted.org/packages/4f/eb/7b97b4a52de8aad73d042e4615651545a254758b63335c086cedafb79aea/tmux_conf-0.16.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-08 21:58:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jaclu",
"github_project": "tmux-conf",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "tmux-conf"
}
