Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/marpogaus/auto-tab-groups

Simple auto tab group creator for specified commands
https://github.com/marpogaus/auto-tab-groups
Last synced: about 6 hours ago
JSON representation
Simple auto tab group creator for specified commands
Host: GitHub
URL: https://github.com/marpogaus/auto-tab-groups
Owner: MArpogaus
License: gpl-3.0
Created: 2024-11-01T23:27:43.000Z (15 days ago)
Default Branch: main
Last Pushed: 2024-11-01T23:47:13.000Z (15 days ago)
Last Synced: 2024-11-02T00:24:13.613Z (15 days ago)
Language: Emacs Lisp
Size: 0 Bytes
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.org
- License: COPYING
Awesome Lists containing this project

README

        # Inspired by: https://github.com/othneildrew/Best-README-Template

#+OPTIONS: toc:nil

[[https://github.com/MArpogaus/auto-tab-groups/graphs/contributors][https://img.shields.io/github/contributors/MArpogaus/auto-tab-groups.svg?style=flat-square]]

[[https://github.com/MArpogaus/auto-tab-groups/network/members][https://img.shields.io/github/forks/MArpogaus/auto-tab-groups.svg?style=flat-square]]

[[https://github.com/MArpogaus/auto-tab-groups/stargazers][https://img.shields.io/github/stars/MArpogaus/auto-tab-groups.svg?style=flat-square]]

[[https://github.com/MArpogaus/auto-tab-groups/issues][https://img.shields.io/github/issues/MArpogaus/auto-tab-groups.svg?style=flat-square]]

[[https://github.com/MArpogaus/auto-tab-groups/blob/main/LICENSE][https://img.shields.io/github/license/MArpogaus/auto-tab-groups.svg?style=flat-square]]

[[https://linkedin.com/in/MArpogaus][https://img.shields.io/badge/-LinkedIn-black.svg?style=flat-square&logo=linkedin&colorB=555]]

* auto tab groups

#+TOC: headlines 2 local

** About The Project

This package provides automated tab group management for Emacs, allowing you to associate commands with specific tab groups.

Heavily inspired by [[https://github.com/fritzgrabo/project-tab-groups][project-tab-groups.el]], this package generalizes the concept to arbitrary commands, providing a more flexible approach to organizing your Emacs workflow.

It automatically switches to or creates tab groups when specified commands are invoked, streamlining navigation and buffer management.

This package has been implemented with simplicity in mind.

It is a very thin layer that leverages Emacs' tab-bar mode for a user-defined workflow, adding very little complexity to it.

An optional "eye-candy" mode is provided for enhanced tab bar styling.

However, by default, any further tab-bar related configurations are handed to the user.

Result with the example configuration provided below:

[[file:screenshot.png]]

** Getting Started

*** Prerequisites

- Emacs 28.1 or later

- =tab-bar= and =project= built-in packages

*** Installation

**** Complete configuration example using =straight.el=

#+begin_src emacs-lisp

  (use-package auto-tab-groups

    :straight (:host github :repo "Marpogaus/auto-tab-groups")

    :after tab-bar project

    :custom

    ;; Automatically create tabs for projects, denote and dirvish buffers

    (auto-tab-groups-create-commands

     '(((project-prompt-project-dir project-switch-to-buffer) . auto-tab-groups-group-name-project)

       ((denote-create-note denote-menu-list-notes consult-denote-find consult-denote-grep) . "denote")

       ((dirvish dirvish-fd) . "dirvish")))

    ;; Close the project tabs when the project buffers are killed

    (auto-tab-groups-close-commands

     '((project-kill-buffers . auto-tab-groups-group-name-project)

       (dirvish-quit . "dirvish")))

    ;; Enable the "eyecandy-mode" for modern tab bars.

    (auto-tab-groups-eyecandy-mode t)

    ;; Define tab group icons (requires nerd-icons)

    (auto-tab-groups-eyecandy-icons

     '(("HOME"                                   . "")

       ("dirvish"                                . "")

       ("denote"                                 . "󱓩")

       (auto-tab-groups-eyecandy-name-is-project . auto-tab-groups-eyecandy-group-icon-project)))

    :init

    (auto-tab-groups-mode))

#+end_src

**** Manual Installation

1. Download =auto-tab-groups.el= and =auto-tab-groups-eyecandy.el=.

2. Place them in your Emacs =load-path=.

3. Add the following to your init file:

            #+begin_src emacs-lisp

  (require 'auto-tab-groups)

  (auto-tab-groups-mode 1)

      #+end_src

If you don't want to enable the provided eye-candy mode for tab-bar styling, you might at least want to display the tab groups, by customizing =tab-bar-format=:

#+begin_src emacs-lisp

  (setq tab-bar-format '(tab-bar-format-tabs-groups

                         ;;... additional format functions

                         ))

#+end_src

Please refer to the documentation of =tab-bar-mode= for details.

** Customization

*** auto-tab-groups

You can customize the behavior of =auto-tab-groups= using the following options:

| Option                             | Type     | Description                                          |

|------------------------------------+----------+------------------------------------------------------|

| =auto-tab-groups-create-commands=    | alist    | Commands to trigger tab group creation or switching. |

| =auto-tab-groups-close-commands=     | alist    | Commands to trigger tab group closure.               |

| =auto-tab-groups-new-choice=         | multiple | Adjust the behavior when new tab is created.         |

| =auto-tab-groups-initial-group-name= | string   | Specify the name of the initial tab group.           |

| =auto-tab-groups-before-create-hook= | hook     | Hook run before tab group creation.                  |

| =auto-tab-groups-after-create-hook=  | hook     | Hook run after tab group creation.                   |

| =auto-tab-groups-before-delete-hook= | hook     | Hook run before tab group deletion.                  |

| =auto-tab-groups-after-delete-hook=  | hook     | Hook run after tab group deletion.                   |

=auto-tab-groups-create-commands= and =auto-tab-groups-close-commands= are alists where:

- CAR: command (symbol) or list of commands.

- CDR: tab group name (string) or function returning a string.

For =create-commands=, the CDR can be a function that receives the command's result.

The tab group is created if it doesn't exist, otherwise, Emacs switches to it.

=close-commands= work similarly, closing the specified tab group after the command is run.

This package provides a helper function to integrate with =project.el=:

=auto-tab-groups-group-name-project= takes an optional directory argument and returns the project name located at that directory, or the current project name if no directory is provided.

It uses =project-name= if the project is defined or falls back to the directory name otherwise.

This is useful when you would like to automatically assign tab groups based on the current project like this:

#+begin_src emacs-lisp

  (setq auto-tab-groups-create-commands

        '(((project-prompt-project-dir project-switch-to-buffer) . auto-tab-groups-group-name-project)

          ;; ... your other commands

          ))

#+end_src

*** auto-tab-groups-eyecandy

The =auto-tab-groups-eyecandy= minor mode provides additional customization options for enhanced tab bar styling:

| Option                                | Type   | Description                   |

|---------------------------------------+--------+-------------------------------|

| =auto-tab-groups-eyecandy-icons=        | alist  | Map tab group names to icons. |

| =auto-tab-groups-eyecandy-tab-height=   | number | Tab height in pixels.         |

| =auto-tab-groups-eyecandy-default-icon= | string | Default icon for tab groups.  |

=auto-tab-groups-eyecandy-icons= is an alist where:

- CAR: tab group name (string) or predicate function.

- CDR: icon string.

This package provides helper functions to integrate with =project.el=:

- =auto-tab-groups-eyecandy-name-is-project=: takes the tab group name as an argument and checks whether it corresponds to an existing project. It returns the project root directory if a match is found or nil otherwise.

- =auto-tab-groups-eyecandy-group-icon-project=: takes a tab group name and returns a suitable icon based on whether the name refers to a project directory, and whether that directory is remote or local. If it is not a project, it returns the default icon.

You can use these in =auto-tab-groups-eyecandy-icons= like this:

#+begin_src emacs-lisp

  (setq auto-tab-groups-eyecandy-icons

        '((auto-tab-groups-eyecandy-name-is-project . auto-tab-groups-eyecandy-group-icon-project)

          ;; ... your other icons

          ))

#+end_src

** Contributing

Any Contributions are greatly appreciated!

** License

Distributed under the [[file:COPYING][GPLv3]] License.

** Contact

[[https://github.com/MArpogaus/][Marcel Arpogaus]] - [[mailto:[email protected]][[email protected]]] (encrypted with [ROT13](https://rot13.com/))

Project Link:

[[https://github.com/MArpogaus/auto-tab-groups]]

** Acknowledgments

- Special thanks to [[https://github.com/fritzgrabo][Fritz Grabo]] for the inspiration and the excellent =project-tab-groups= package.