feat(tmux): improve session creation script

Add a simple README to document it

modules/home-manager/cli/tmux/default.nix

@@ -52,7 +52,7 @@ in
         bind -n M-F4 if 'tmux has-session -t 4' {switch-client -t 4} {display-popup -E -E 'create-tmux-session -i 4'}
 
         # Alt+F10 for launching my Nix project
-        bind -n M-F10 run 'create-tmux-session -n config -p nix "run:nvim ." vsplit:20'
+        bind -n M-F10 run 'create-tmux-session -n config -r nix "run:nvim ." vsplit:20'
 
         # change window with Alt+{1..5}
         bind -n -N "Goto window 1" M-1 select-window -T -t 1

modules/home-manager/cli/tmux/files/README.md

@@ -0,0 +1,68 @@
+# Create a tmux session
+
+This script help me to create a tmux session and manage related windows, panes and commands.
+
+## Usage
+
+```
+create-tmux-session -n <name> -i <id> -p <project> <command> <command>
+
+-n --name <name>        define a session name
+-i --id <id>            define a session id,
+-r --repo <project>     define the repo used as base directory if not defined
+                        'ghq' and 'fzf' will be use to let you select one
+
+<command>               a command launched in the new created session. you can
+                        use it many time.
+```
+
+## Commands
+
+Commands create windows and panes, launch program and change current directory related to git project (managed by [ghq][ghq]).
+Each command can take a parameter which is mandatpry if no default value exists.
+If parameter contains spaces, must be surrounded by quotes / double quote.
+
+* `vsplit`: split current pane vertically, parameter define the vertical size of the created pane in percent (default 20).
+    ```bash
+    # split first windows, new created pane will take 50% of vertical space
+    create-tmux-session.sh -n mysession vsplit:50
+    ```
+* `hsplit`: split current pane horizontally
+    ```bash
+    # split first windows, new created pane will take 50% of horizontal space
+    create-tmux-session.sh -n mysession hsplit:50
+    ```
+* `neww`: create a new windows, parameter define the new windows name (not mandatory)
+    ```bash
+    # Create a new window name 'shell'
+    create-tmux-session.sh -n mysession -r blog neww:shell
+    ```
+* `run`: launch a command in last created element (window / pane ), parameter define command.
+    ```bash
+    # Just launch ls
+    create-tmux-session.sh -n mysession -r blog run:ls
+
+    # This time with parameters
+    create-tmux-session.sh -n mysession -r blog "run:ls -la"
+    ```
+* `repo`: change current directory to given git repository in parameter.
+    If not parameter is provided, script will launch a menu to select one with `fzf`.
+    New directory will take effect for new created panes / windows after `repo` command.
+    ```bash
+    # change current directory ti ephase:nix repo
+    create-tmux-session.sh -n mysession -r blog repo:ephase/nix neww
+    ```
+
+## Example
+
+Create a new session for my blog repository, launch Neovim, split pane to create a terminal pane bellow text editor then create a new window to lanche development server
+
+```bash
+create-tmux-session.sh -n blog -r ephase/blog 'run:nvim .' vsplit neww 'run:task serve'
+```
+
+Create a new session for my blog like previous example but open new windows with my nix repository and launch Neovim
+
+```bash
+create-tmux-session.sh -n blog -r ephase/blog 'run:nvim .' vsplit neww 'run:task serve' repo:ephase/nix neww:nix 'run:nvim .'
+```

modules/home-manager/cli/tmux/files/create-tmux-session.sh

@@ -5,6 +5,47 @@ set -o pipefail
 DEBUG=0
 declare -a COMMANDS
 
+help() {
+  cat <<EOF
+${0}
+
+Create a tmux session with defined elements (windows, panes, launch command).
+This script need 'ghq' and 'fzf',
+
+USAGE
+-----
+create-tmux-session -n <name> -i <id> -p <project> <command> <command>
+
+-n --name <name>        define a session name     
+-i --id <id>            define a session id,
+-r --repo <project>     define the repo used as base directory if not defined
+                        'ghq' and 'fzf' will be use to let you select one
+
+<command>               a command launched in the new created session. you can  
+                        use it many time.
+
+COMMANDS
+--------
+All commands take only one parameter separated rom command by coma (':') for 
+example 'neww:shell'.
+
+vsplit    Split current pane vertically 
+          parameter: new pane vertical size in % (default 20)
+
+hsplit    Split current pane horizontally (default 20)
+          parameter: new pane horizontal size in % (default 20)
+
+neww      Create a new window, parameter: windows name
+
+run       Run command into last created element (pane, window)
+          parameter: command
+
+repo      Change repo, useful to create a pane / window with a different base
+          directory
+          parameter: repo name
+EOF
+}
+
 error() {
   local message
   printf -v message "\e[31mERROR:\e[0m %s\n" "$1"
@@ -30,13 +71,17 @@ process_args() {
       SESSION_NAME="$2"
       shift
       ;;
-    -p | --project-name | --window)
+    -r | --repository-name | --repo)
       PROJECT="$2"
       shift
       ;;
     -d | --debug)
       DEBUG=1
       ;;
+    -h | --help)
+      help
+      exit 0
+      ;;
     *)
       COMMANDS+=("$1")
       ;;
@@ -45,11 +90,19 @@ process_args() {
   done
 }
 
+check_command() {
+  local command="$1"
+  if ! command -v "${command}" >/dev/null 2>&1; then
+    error "Command '$command' not available"
+    exit 2
+  fi
+}
+
 has_session() {
   tmux has-session -t "${SESSION_NAME:-$SESSION_ID}" 2>/dev/null
 }
 
-get_project_path() {
+get_repo_path() {
   local identifier="${1}"
   debug "get project path with identifier '$identifier'"
   if [[ -z "$identifier" ]]; then
@@ -67,6 +120,13 @@ is_running_in_tmux() {
   fi
 }
 
+check_available_commands() {
+  # Check commands dependencies
+  for c in fzf ghq; do
+    check_command "$c"
+  done
+}
+
 check_script_inputs() {
   debug "check script inputs"
   if [[ -z "$SESSION_ID" ]] && [[ -z "$SESSION_NAME" ]]; then
@@ -125,10 +185,10 @@ tmux_run() {
   fi
 }
 
-tmux_project() {
+tmux_repo() {
   local arg="$1"
   debug "execute project with arg '${arg}'"
-  get_project_path "$arg"
+  get_repo_path "$arg"
 }
 
 create_session() {
@@ -139,11 +199,12 @@ create_session() {
 }
 
 main() {
+  check_available_commands
   process_args "$@"
   is_running_in_tmux
   check_script_inputs
   if ! has_session "${SESSION_NAME}"; then
-    get_project_path "${PROJECT}"
+    get_repo_path "${PROJECT}"
     create_session
     # Process tmux commands passed with command line
     for command in "${COMMANDS[@]}"; do