{"id":13592678,"url":"https://github.com/ofirgall/tmux-window-name","last_synced_at":"2025-04-08T23:34:02.385Z","repository":{"id":40271598,"uuid":"462735031","full_name":"ofirgall/tmux-window-name","owner":"ofirgall","description":"A plugin to name your tmux windows smartly.","archived":false,"fork":false,"pushed_at":"2024-05-28T11:25:33.000Z","size":92,"stargazers_count":200,"open_issues_count":3,"forks_count":18,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-08-02T16:45:33.456Z","etag":null,"topics":["tmux"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ofirgall.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-23T12:56:09.000Z","updated_at":"2024-07-26T01:59:42.000Z","dependencies_parsed_at":"2024-03-18T15:12:32.977Z","dependency_job_id":null,"html_url":"https://github.com/ofirgall/tmux-window-name","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ofirgall%2Ftmux-window-name","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ofirgall%2Ftmux-window-name/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ofirgall%2Ftmux-window-name/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ofirgall%2Ftmux-window-name/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ofirgall","download_url":"https://codeload.github.com/ofirgall/tmux-window-name/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223346940,"owners_count":17130531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["tmux"],"created_at":"2024-08-01T16:01:11.989Z","updated_at":"2025-04-08T23:34:02.376Z","avatar_url":"https://github.com/ofirgall.png","language":"Python","funding_links":[],"categories":["Python","Status Bar"],"sub_categories":[],"readme":"# Better Window Names for tmux\n\nA plugin to name your tmux windows smartly, like IDE's.\n\n![Tmux Window Name Screenshot](screenshots/example.png)\n\n## Index\n* [Use case](#use-case)\n* [Usage](#usage)\n* [How it works](#how-it-works)\n* [Installation](#installation)\n* [Configuration Options](#configuration-options)\n\n## Dependencies\n\n* tmux (Tested on 3.0a)\n* Python 3.6.8+ (Maybe can be lower, tested on 3.6.8)\n* pip\n* [libtmux](https://github.com/tmux-python/libtmux) \u003e0.16\n\n## Use case\n\nIf you are using tmux as your main multiplexer you probably found yourself with 5+ windows per session with indexed names but no information about whats going on in the windows.\n\nYou tried to configure `automatic-rename` and `automatic-rename-format` but you found yourself pretty limited.\n\nThis plugin comes to solve those issues to name your windows inspired by IDE tablines.\\\nIt makes sure to show you the shortest path possible!\n\n#### Examples\nThis session:\n```\n1. ~/workspace/my_project\n2. ~/workspace/my_project/tests/\n3. ~/workspace/my_other_project\n4. ~/workspace/my_other_project/tests\n```\nWill display:\n```\n1. my_project\n2. my_project/tests\n3. my_other_project\n4. my_other_project/tests\n```\n\n---\n\nIt knows which programs runs\n```\n1. ~/workspace/my_project (with nvim)\n2. ~/workspace/my_project\n3. ~/workspace/my_other_project (with git diff)\n4. ~/workspace/my_other_project\n```\nWill display:\n```\n1. nvim:my_project\n2. my_project\n3. git diff:my_other_project\n4. my_other_project\n```\n\nFor more scenarios you check out the [tests](tests/test_exclusive_paths.py).\n\n## Usage\n[Install](#installation) the plugin and let it name your windows :)\n\n_**Note**_: if you are using [tmux-resurrect](https://github.com/tmux-plugins/tmux-resurrect) `tmux-window-name` must be loaded before `tmux-resurrect`\n\nYou can `tmux rename-window` manually to set your own window names, to re-enable automatic renames set run `tmux rename-window \"\"`\n\nMake sure your configuration/other plugins doesn't turn on `automatic-rename` and doesn't rename your windows.\n\n### Automatic rename after launching neovim\nBy default `tmux-window-name` hooks `after-select-window` which trigged when switching windows.\n\nYou can add autocmd to rename after nvim launches and stops as so:\n```lua\nlocal uv = vim.uv\n\nvim.api.nvim_create_autocmd({ 'VimEnter', 'VimLeave' }, {\n\tcallback = function()\n\t\tif vim.env.TMUX_PLUGIN_MANAGER_PATH then\n\t\t\tuv.spawn(vim.env.TMUX_PLUGIN_MANAGER_PATH .. '/tmux-window-name/scripts/rename_session_windows.py', {})\n\t\tend\n\tend,\n})\n```\n\n### Automatic rename after changing dir\nBy default `tmux-window-name` hooks `after-select-window` which trigged when switching windows, you can add hook in your `.shellrc` to execute `tmux-window-name`\n##### .zshrc\n```bash\ntmux-window-name() {\n\t($TMUX_PLUGIN_MANAGER_PATH/tmux-window-name/scripts/rename_session_windows.py \u0026)\n}\n\nadd-zsh-hook chpwd tmux-window-name\n```\n\n#### Hooks Used\nMake sure the hooks that used aren't overridden.\n* @resurrect-hook-pre-restore-all\n* @resurrect-hook-post-restore-all\n\n---\n\n## How it works\nEach time you unfocus from a pane, the plugin looks for every active pane in your session windows.\n\n_**Note**_: if you have a better hook in mind make sure to notify me!\n\n1. If shell is running, it shows the current dir as short as possible, `long_dir/a` -\u003e `a`, it avoids [intersections](#Intersections) too!\n1. If \"regular\" program is running it shows the program with the args, `less ~/my_file` -\u003e `less ~/my_file`.\n1. If \"special\" program is running it shows the program with the dir attached, `git diff` (in `long_dir/a`) -\u003e `git diff:a`, it avoids [intersections](#Intersections) too!\n\n### Intersections\n\nTo make the shortest path as possible the plugin finds the shortest not common path if your windows.\n\n--- \n\n## Installation\n\n### Install libtmux (must)\n_**Note**_: Make sure you are using the `user` python and not `sudo` python or `virutalenv` python!\n\n```sh\npython3 -m pip install --user libtmux\n```\n\n### Install dataclasses (for Python 3.6.X only)\n```sh\npython3 -m pip install dataclasses --user\n```\n\n### Installation with [Tmux Plugin Manager](https://github.com/tmux-plugins/tpm) (recommended)\n\nAdd plugin to the list of TPM plugins:\n\n```tmux.conf\nset -g @plugin 'ofirgall/tmux-window-name'\n```\n\n_**Note**_: set `tmux-window-name` before `tmux-resurrect` (if you are using `tmux-resurrect`)\n\n```tmux.conf\nset -g @plugin 'ofirgall/tmux-window-name'\nset -g @plugin 'tmux-plugins/tmux-resurrect'\n```\n\nPress prefix + I to install it.\n\n### Manual Installation\n\nClone the repo:\n\n```bash\n$ git clone https://github.com/ofirgall/tmux-window-name.git ~/clone/path\n```\n\nAdd this line to your .tmux.conf:\n\n```tmux.conf\nrun-shell ~/clone/path/tmux_window_name.tmux\n```\n\nReload TMUX environment with:\n\n```bash\n$ tmux source-file ~/.tmux.conf\n```\n\n## Configuration Options\n_**Note**_: All options are evaluated with [eval](https://docs.python.org/3/library/functions.html#eval) be careful!\n\n### `@tmux_window_name_shells`\n\nShell programs, will show dir instead of the program\n\n```tmux.conf\nset -g @tmux_window_name_shells \"['bash', 'fish', 'sh', 'zsh']\"\n```\n\n### `@tmux_window_name_dir_programs`\n\nPrograms that will show the dir name too.\n\nE.g: `git diff` running in `long_dir/my_repo` will show `git diff:my_repo`\n\n```tmux.conf\nset -g @tmux_window_dir_programs \"['nvim', 'vim', 'vi', 'git']\"\n```\n\n### `@tmux_window_name_ignored_programs`\n\nPrograms that will be skipped/ignored when looking for active program.\n\n```tmux.conf\nset -g @tmux_window_name_ignored_programs \"['sqlite3']\" # Default is []\n```\n\n### `@tmux_window_name_max_name_len`\n\nMaximum name length of a window\n\n```tmux.conf\nset -g @tmux_window_name_max_name_len \"20\"\n```\n\n### `@tmux_window_name_use_tilde`\n\nReplace `$HOME` with `~` in window names\n\n```tmux.conf\nset -g @tmux_window_name_use_tilde \"False\"\n```\n\n### `@tmux_window_name_show_program_args`\n\nShow arguments that the program has been ran with.\n\n```tmux.conf\nset -g @tmux_window_name_show_program_args \"True\"\n```\n\n### `@tmux_window_name_substitute_sets`\n\nReplace program command lines with [re.sub](https://docs.python.org/3/library/re.html#re.sub). \\\nThe options expect list of tuples with 2 elements, `pattern` and `repl`. \\\nE.g: The example below will replace `/usr/bin/python3 /usr/bin/ipython3` with `ipython3`, and the same for ipython2\n\nNote: use `~/.tmux/plugins/tmux-window-name/scripts/rename_session_windows.py --print_programs` to see the full program command line and the results of the substitute.\n\n```tmux.conf\nset -g @tmux_window_name_substitute_sets \"[('.+ipython2', 'ipython2'), ('.+ipython3', 'ipython3')]\"\n\n# Same example but with regex groups\nset -g @tmux_window_name_substitute_sets \"[('.+ipython([32])', 'ipython\\g\u003c1\u003e')]\"\n\n# Default Value:\nset -g @tmux_window_name_substitute_sets \"[('.+ipython([32])', 'ipython\\g\u003c1\u003e'), ('^(/usr)?/bin/(.+)', '\\g\u003c2\u003e'), ('(bash) (.+)/(.+[ $])(.+)', '\\g\u003c3\u003e\\g\u003c4\u003e'), ('.+poetry shell', 'poetry')]\"\n\t# 0: from example\n\t# 1: removing `/usr/bin` and `/bin` prefixes of files\n\t# 2: removing `bash /long/path/for/bashscript`\n\t# 3: changing \"poetry shell\" to \"poetry\"\n```\n\n### `@tmux_window_name_dir_substitute_sets`\n\nReplace dir lines with [re.sub](https://docs.python.org/3/library/re.html#re.sub). \\\nThe options expect list of tuples with 2 elements, `pattern` and `repl` as above. \nE.g: The example below will replace `tmux-resurrect` with `resurrect`\n\n```tmux.conf\nset -g @tmux_window_name_dir_substitute_sets \"[('tmux-(.+)', '\\\\g\u003c1\u003e')]\"\n\n# Default Value:\nset -g @tmux_window_name_dir_substitute_sets \"[]\"\n```\n\n### `@tmux_window_name_icon_style`\n\nConfigure how icons are displayed in window names. \\\nAvailable styles:\n- `name`: Show only program name (default)\n- `icon`: Show only icon\n- `name_and_icon`: Show both icon and program name\n\n```tmux.conf\n# Show only icons\nset -g @tmux_window_name_icon_style \"'icon'\"\n\n# Show icons with program names\nset -g @tmux_window_name_icon_style \"'name_and_icon'\"\n\n# Default Value:\nset -g @tmux_window_name_icon_style \"'name'\"\n```\n\n### `@tmux_window_name_custom_icons`\n\nCustomize icons for specific programs. \\\nThe value should be a dictionary mapping program names to their icons.\n\n```tmux.conf\n# Custom icons example\nset -g @tmux_window_name_custom_icons '{\"python\": \"🐍\", \"custom_app\": \"📦\"}'\n\n# Default Value:\nset -g @tmux_window_name_custom_icons '{}'\n```\n\n_**Note**_: Icons can be any Unicode characters, including emoji or Nerd Font icons. \\\nIf using Nerd Font icons, make sure your terminal supports them.\n\n---\n\n## Debug Configuration Options\n\n### `@tmux_window_name_log_level`\n\nSet log level of the script. \\\nLogs output go to `/tmp/tmux-window-name.log`\n\n```tmux.conf\n# Enable debug logs\nset -g @tmux_window_name_log_level \"'DEBUG'\"\n\n# Default Value:\nset -g @tmux_window_name_log_level \"'WARNING'\"\n```\n\n---\n\n# Development\nRun `ruff format` before applying PR\n\n# Testing\nRun `pytest` at the root dir\n\n---\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fofirgall%2Ftmux-window-name","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fofirgall%2Ftmux-window-name","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fofirgall%2Ftmux-window-name/lists"}