v1.0.0

Close #25

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ### master
 
+### v1.0.0, 2014-08-30
+- show spinner during the save process
+- add screencast script
+- make default program running list even more conservative
+
+### v0.4.0, 2014-08-29
+- change plugin name to `tmux-resurrect`. Change all the variable names.
+
+### v0.3.0, 2014-08-29
+- bugfix: when top is running the pane `$PWD` can't be saved. This was causing
+  issues during the restore and is now fixed.
+- restoring sessions multiple times messes up the whole environment - new panes
+  are all around. This is now fixed - pane restorations are now idempotent.
+- if pane exists from before session restore - do not restore the process within
+  it. This makes the restoration process even more idempotent.
+- more panes within a window can now be restored
+- restore window zoom state
+
 ### v0.2.0, 2014-08-29
 - bugfix: with vim 'session' strategy, if the session file does not exist - make
   sure vim does not contain `-S` flag

CONTRIBUTING.md

@@ -6,7 +6,7 @@ Code contributions are welcome!
 
 If you find a bug please report it in the issues. When reporting a bug please
 attach:
-- a file symlinked to `~/.tmux/sessions/last`.
+- a file symlinked to `~/.tmux/resurrect/last`.
 - your `.tmux.conf`
 - if you're getting an error paste it to a [gist](https://gist.github.com/) and
   link it in the issue

README.md

@@ -1,17 +1,22 @@
-# Tmux Session Saver
+# Tmux Resurrect
 
-Persists `tmux` environment across system restarts.
+Restore `tmux` environment after a system restart.
 
-Tmux is great, except when you have to restart your computer. You loose all the
+Tmux is great, except when you have to restart the computer. You loose all the
 running programs, working directories, pane layouts etc.
 There are helpful management tools out there, but they require initial
 configuration and continuous updates as your workflow evolves or you start new
 projects.
 
-Enter `tmux-session-saver`: tmux persistence without configuration so there are
+`tmux-resurrect` saves all the little details from tmux environment so it
-no interruptions in your workflow.
+can be completely restored after a system restart (or when you feel like it).
+No configuration is required. You should feel like you never quit tmux.
 
-It will even (optionally) [restore vim sessions](#restoring-vim-sessions)!
+It even (optionally) [restores vim sessions](#restoring-vim-sessions)!
+
+### Screencast
+
+[![screencast screenshot](/video/screencast_img.png)](https://vimeo.com/104763018)
 
 ### Key bindings
 
@@ -28,8 +33,10 @@ This plugin goes to great lengths to save and restore all the details from your
 - **exact pane layouts** within windows
 - active and alternative session
 - active and alternative window for each session
+- windows with focus
 - active pane for each window
-- programs running within a pane! More details in the [configuration section](#configuration).
+- programs running within a pane! More details in the
+  [configuration section](#configuration).
 - restoring vim sessions (optional). More details in
   [restoring vim sessions](#restoring-vim-sessions).
 
@@ -41,7 +48,7 @@ Add plugin to the list of TPM plugins in `.tmux.conf`:
 
     set -g @tpm_plugins "           \
       tmux-plugins/tpm              \
-      tmux-plugins/tmux-session-saver  \
+      tmux-plugins/tmux-resurrect   \
     "
 
 Hit `prefix + I` to fetch the plugin and source it. You should now be able to
@@ -51,11 +58,11 @@ use the plugin.
 
 Clone the repo:
 
-    $ git clone https://github.com/tmux-plugins/tmux-session-saver ~/clone/path
+    $ git clone https://github.com/tmux-plugins/tmux-resurrect ~/clone/path
 
 Add this line to the bottom of `.tmux.conf`:
 
-    run-shell ~/clone/path/session_saver.tmux
+    run-shell ~/clone/path/resurrect.tmux
 
 Reload TMUX environment:
 
@@ -66,38 +73,40 @@ You should now be able to use the plugin.
 
 ### Configuration
 
-Only a conservative list of programs is restored by default:
+Configuration is not required - but it enables extra features.
-`vi vim emacs man less more tail top htop irssi irb pry "~rails console"`.
+
+Only a conservative list of programs is restored by default:<br/>
+`vi vim emacs man less more tail top htop irssi`.
 Open a github issue if you think some other program should be on the default list.
 
 - Restore additional programs with the setting in `.tmux.conf`:
 
-        set -g @session-saver-processes 'ssh psql mysql sqlite3'
+        set -g @resurrect-processes 'ssh psql mysql sqlite3'
 
 - Programs with arguments should be double quoted:
 
-        set -g @session-saver-processes 'some_program "git log"'
+        set -g @resurrect-processes 'some_program "git log"'
 
 - Start with tilde to restore a program whose process contains target name:
 
-        set -g @session-saver-processes 'some_program "~rails server"'
+        set -g @resurrect-processes 'irb pry "~rails server" "~rails console"'
 
 - Don't restore any programs:
 
-        set -g @session-saver-processes 'false'
+        set -g @resurrect-processes 'false'
 
 - Restore **all** programs (be careful with this!):
 
-        set -g @session-saver-processes ':all:'
+        set -g @resurrect-processes ':all:'
 
 #### Restoring vim sessions
 
-- save vim sessions - I recommend [tpope/vim-obsession](tpope/vim-obsession)
+- save vim sessions. I recommend [tpope/vim-obsession](tpope/vim-obsession).
 - in `.tmux.conf`:
 
-        set -g @session-saver-strategy-vim "session"
+        set -g @resurrect-strategy-vim "session"
 
-`tmux-session-saver` will now restore vim sessions if `Sessions.vim` file is
+`tmux-resurrect` will now restore vim sessions if `Sessions.vim` file is
 present.
 
 ### Reporting bugs and contributing

resurrect.tmux

@@ -9,7 +9,7 @@ set_save_bindings() {
 	local key_bindings=$(get_tmux_option "$save_option" "$default_save_key")
 	local key
 	for key in $key_bindings; do
-		tmux bind-key "$key" run-shell "$CURRENT_DIR/scripts/session_saver.sh"
+		tmux bind-key "$key" run-shell "$CURRENT_DIR/scripts/save.sh"
 	done
 }
 
@@ -17,7 +17,7 @@ set_restore_bindings() {
 	local key_bindings=$(get_tmux_option "$restore_option" "$default_restore_key")
 	local key
 	for key in $key_bindings; do
-		tmux bind-key "$key" run-shell "$CURRENT_DIR/scripts/session_restorer.sh"
+		tmux bind-key "$key" run-shell "$CURRENT_DIR/scripts/restore.sh"
 	done
 }
 

scripts/helpers.sh

@@ -1,6 +1,5 @@
-# configurable constants
+default_resurrect_dir="$HOME/.tmux/resurrect"
-default_sessions_dir="$HOME/.tmux/sessions"
+resurrect_dir_option="@resurrect-dir"
-sessions_dir_option="@session-saver-dir"
 
 SUPPORTED_VERSION="1.9"
 
@@ -52,15 +51,15 @@ remove_first_char() {
 
 # path helpers
 
-sessions_dir() {
+resurrect_dir() {
-	echo $(get_tmux_option "$sessions_dir_option" "$default_sessions_dir")
+	echo $(get_tmux_option "$resurrect_dir_option" "$default_resurrect_dir")
 }
 
-session_path() {
+resurrect_file_path() {
 	local timestamp="$(date +"%Y-%m-%dT%H:%M:%S")"
-	echo "$(sessions_dir)/tmux_session_${timestamp}.txt"
+	echo "$(resurrect_dir)/tmux_resurrect_${timestamp}.txt"
 }
 
-last_session_path() {
+last_resurrect_file() {
-	echo "$(sessions_dir)/last"
+	echo "$(resurrect_dir)/last"
 }

scripts/process_restore_helpers.sh

@@ -13,7 +13,7 @@ restore_pane_process() {
 	local window_number="$3"
 	local pane_index="$4"
 	local dir="$5"
-	if _process_should_be_restored "$pane_full_command"; then
+	if _process_should_be_restored "$pane_full_command" "$session_name" "$window_number" "$pane_index"; then
 		tmux switch-client -t "${session_name}:${window_number}"
 		tmux select-pane -t "$pane_index"
 
@@ -21,8 +21,6 @@ restore_pane_process() {
 			local strategy_file="$(_get_strategy_file "$pane_full_command")"
 			local strategy_command="$($strategy_file "$pane_full_command" "$dir")"
 			tmux send-keys "$strategy_command" "C-m"
-			# tmux send-keys "Strategy! $pane_full_command $strategy_file"
-			# tmux send-keys "Strategy! $strategy_command"
 		else
 			# just invoke the command
 			tmux send-keys "$pane_full_command" "C-m"
@@ -34,7 +32,14 @@ restore_pane_process() {
 
 _process_should_be_restored() {
 	local pane_full_command="$1"
-	if _restore_all_processes; then
+	local session_name="$2"
+	local window_number="$3"
+	local pane_index="$4"
+	if is_pane_registered_as_existing "$session_name" "$window_number" "$pane_index"; then
+		# Scenario where pane existed before restoration, so we're not
+		# restoring the proces either.
+		return 1
+	elif _restore_all_processes; then
 		return 0
 	elif _process_on_the_restore_list "$pane_full_command"; then
 		return 0

scripts/restore.sh

@@ -7,6 +7,12 @@ source "$CURRENT_DIR/helpers.sh"
 source "$CURRENT_DIR/process_restore_helpers.sh"
 source "$CURRENT_DIR/spinner_helpers.sh"
 
+# Global variable.
+# Used during the restore: if a pane already exists from before, it is
+# saved in the array in this variable. Later, process running in existing pane
+# is also not restored. That makes the restoration process more idempotent.
+EXISTING_PANES_VAR=""
+
 is_line_type() {
 	local line_type="$1"
 	local line="$2"
@@ -15,13 +21,38 @@ is_line_type() {
 }
 
 check_saved_session_exists() {
-	local saved_session="$(last_session_path)"
+	local resurrect_file="$(last_resurrect_file)"
-	if [ ! -f $saved_session ]; then
+	if [ ! -f $resurrect_file ]; then
-		display_message "Saved tmux session not found!"
+		display_message "Tmux resurrect file not found!"
 		return 1
 	fi
 }
 
+pane_exists() {
+	local session_name="$1"
+	local window_number="$2"
+	local pane_index="$3"
+	tmux list-panes -t "${session_name}:${window_number}" -F "#{pane_index}" 2>/dev/null |
+		\grep -q "^$pane_index$"
+}
+
+register_existing_pane() {
+	local session_name="$1"
+	local window_number="$2"
+	local pane_index="$3"
+	local pane_custom_id="${session_name}:${window_number}:${pane_index}"
+	local delimiter=$'\t'
+	EXISTING_PANES_VAR="${EXISTING_PANES_VAR}${delimiter}${pane_custom_id}"
+}
+
+is_pane_registered_as_existing() {
+	local session_name="$1"
+	local window_number="$2"
+	local pane_index="$3"
+	local pane_custom_id="${session_name}:${window_number}:${pane_index}"
+	[[ "$EXISTING_PANES_VAR" =~ "$pane_custom_id" ]]
+}
+
 window_exists() {
 	local session_name="$1"
 	local window_number="$2"
@@ -68,23 +99,28 @@ new_pane() {
 	local window_number="$2"
 	local window_name="$3"
 	local dir="$4"
-	tmux split-window -t "${session_name}:${window_number}" -c "$dir"
+	tmux split-window -t "${session_name}:${window_number}" -c "$dir" -h
+	tmux resize-pane  -t "${session_name}:${window_number}" -L "999"
 }
 
 restore_pane() {
 	local pane="$1"
-	echo "$pane" |
 	while IFS=$'\t' read line_type session_name window_number window_name window_active window_flags pane_index dir pane_active pane_command pane_full_command; do
+		dir="$(remove_first_char "$dir")"
 		window_name="$(remove_first_char "$window_name")"
 		pane_full_command="$(remove_first_char "$pane_full_command")"
-		if window_exists "$session_name" "$window_number"; then
+		if pane_exists "$session_name" "$window_number" "$pane_index"; then
+			# Pane exists, no need to create it!
+			# Pane existence is registered. Later, it's process also isn't restored.
+			register_existing_pane "$session_name" "$window_number" "$pane_index"
+		elif window_exists "$session_name" "$window_number"; then
 			new_pane "$session_name" "$window_number" "$window_name" "$dir"
 		elif session_exists "$session_name"; then
 			new_window "$session_name" "$window_number" "$window_name" "$dir"
 		else
 			new_session "$session_name" "$window_number" "$window_name" "$dir"
 		fi
-	done
+	done < <(echo "$pane")
 }
 
 restore_state() {
@@ -96,19 +132,20 @@ restore_state() {
 	done
 }
 
-restore_all_sessions() {
+restore_all_panes() {
 	while read line; do
 		if is_line_type "pane" "$line"; then
 			restore_pane "$line"
 		fi
-	done < $(last_session_path)
+	done < $(last_resurrect_file)
 }
 
 restore_all_pane_processes() {
 	if restore_pane_processes_enabled; then
 		local pane_full_command
-		awk 'BEGIN { FS="\t"; OFS="\t" } /^pane/ && $11 !~ "^:$" { print $2, $3, $7, $8, $11; }' $(last_session_path) |
+		awk 'BEGIN { FS="\t"; OFS="\t" } /^pane/ && $11 !~ "^:$" { print $2, $3, $7, $8, $11; }' $(last_resurrect_file) |
 			while IFS=$'\t' read session_name window_number pane_index dir pane_full_command; do
+				dir="$(remove_first_char "$dir")"
 				pane_full_command="$(remove_first_char "$pane_full_command")"
 				restore_pane_process "$pane_full_command" "$session_name" "$window_number" "$pane_index" "$dir"
 			done
@@ -116,22 +153,29 @@ restore_all_pane_processes() {
 }
 
 restore_pane_layout_for_each_window() {
-	\grep '^window' $(last_session_path) |
+	\grep '^window' $(last_resurrect_file) |
 		while IFS=$'\t' read line_type session_name window_number window_active window_flags window_layout; do
 			tmux select-layout -t "${session_name}:${window_number}" "$window_layout"
 		done
 }
 
 restore_active_pane_for_each_window() {
-	awk 'BEGIN { FS="\t"; OFS="\t" } /^pane/ && $7 != 0 && $9 == 1 { print $2, $3, $7; }' $(last_session_path) |
+	awk 'BEGIN { FS="\t"; OFS="\t" } /^pane/ && $9 == 1 { print $2, $3, $7; }' $(last_resurrect_file) |
 		while IFS=$'\t' read session_name window_number active_pane; do
 			tmux switch-client -t "${session_name}:${window_number}"
 			tmux select-pane -t "$active_pane"
 		done
 }
 
+restore_zoomed_windows() {
+	awk 'BEGIN { FS="\t"; OFS="\t" } /^window/ && $5 ~ /Z/ { print $2, $3; }' $(last_resurrect_file) |
+		while IFS=$'\t' read session_name window_number; do
+			tmux resize-pane -t "${session_name}:${window_number}" -Z
+		done
+}
+
 restore_active_and_alternate_windows() {
-	awk 'BEGIN { FS="\t"; OFS="\t" } /^window/ && $5 ~ /[*-]/ { print $2, $4, $3; }' $(last_session_path) |
+	awk 'BEGIN { FS="\t"; OFS="\t" } /^window/ && $5 ~ /[*-]/ { print $2, $4, $3; }' $(last_resurrect_file) |
 		sort -u |
 		while IFS=$'\t' read session_name active_window window_number; do
 			tmux switch-client -t "${session_name}:${window_number}"
@@ -143,21 +187,22 @@ restore_active_and_alternate_sessions() {
 		if is_line_type "state" "$line"; then
 			restore_state "$line"
 		fi
-	done < $(last_session_path)
+	done < $(last_resurrect_file)
 }
 
 main() {
 	if supported_tmux_version_ok && check_saved_session_exists; then
-		start_spinner
+		start_spinner "Restoring..." "Tmux restore complete!"
-		restore_all_sessions
+		restore_all_panes
-		restore_all_pane_processes
 		restore_pane_layout_for_each_window >/dev/null 2>&1
+		restore_all_pane_processes
 		# below functions restore exact cursor positions
 		restore_active_pane_for_each_window
+		restore_zoomed_windows
 		restore_active_and_alternate_windows
 		restore_active_and_alternate_sessions
 		stop_spinner
-		display_message "Restored all Tmux sessions!"
+		display_message "Tmux restore complete!"
 	fi
 }
 main

scripts/save.sh

@@ -2,7 +2,9 @@
 
 CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
+source "$CURRENT_DIR/scripts/variables.sh"
 source "$CURRENT_DIR/helpers.sh"
+source "$CURRENT_DIR/spinner_helpers.sh"
 
 pane_format() {
 	local delimiter=$'\t'
@@ -21,7 +23,7 @@ pane_format() {
 	format+="${delimiter}"
 	format+="#{pane_index}"
 	format+="${delimiter}"
-	format+="#{pane_current_path}"
+	format+=":#{pane_current_path}"
 	format+="${delimiter}"
 	format+="#{pane_active}"
 	format+="${delimiter}"
@@ -88,19 +90,21 @@ dump_state() {
 	tmux display-message -p "$(state_format)"
 }
 
-save_all_sessions() {
+save_all() {
-	local session_path="$(session_path)"
+	local resurrect_file_path="$(resurrect_file_path)"
-	mkdir -p "$(sessions_dir)"
+	mkdir -p "$(resurrect_dir)"
-	dump_panes   >  $session_path
+	dump_panes   >  $resurrect_file_path
-	dump_windows >> $session_path
+	dump_windows >> $resurrect_file_path
-	dump_state   >> $session_path
+	dump_state   >> $resurrect_file_path
-	ln -fs "$session_path" "$(last_session_path)"
+	ln -fs "$resurrect_file_path" "$(last_resurrect_file)"
-	display_message "Saved all Tmux sessions!"
 }
 
 main() {
 	if supported_tmux_version_ok; then
-		save_all_sessions
+		start_spinner "Saving..." "Tmux environment saved!"
+		save_all
+		stop_spinner
+		display_message "Tmux environment saved!"
 	fi
 }
 main

scripts/spinner_helpers.sh

@@ -1,5 +1,5 @@
 start_spinner() {
-	$CURRENT_DIR/tmux_spinner.sh "Restoring sessions..." "Restored all Tmux sessions!" &
+	$CURRENT_DIR/tmux_spinner.sh "$1" "$2" &
 	export SPINNER_PID=$!
 }
 

scripts/variables.sh

@@ -1,13 +1,13 @@
 # key bindings
 default_save_key="M-s"
-save_option="@session-saver-save"
+save_option="@resurrect-save"
 
 default_restore_key="M-r"
-restore_option="@session-saver-restore"
+restore_option="@resurrect-restore"
 
 # default processes that are restored
-default_proc_list_option="@session-saver-default-processes"
+default_proc_list_option="@resurrect-default-processes"
-default_proc_list='vi vim emacs man less more tail top htop irssi irb pry "~rails console"'
+default_proc_list='vi vim emacs man less more tail top htop irssi'
 
 # User defined processes that are restored
 #  'false' - nothing is restored
@@ -15,9 +15,9 @@ default_proc_list='vi vim emacs man less more tail top htop irssi irb pry "~rail
 #
 # user defined list of programs that are restored:
 #  'my_program foo another_program'
-restore_processes_option="@session-saver-processes"
+restore_processes_option="@resurrect-processes"
 restore_processes=""
 
 # Defines part of the user variable. Example usage:
-#   set -g @session-saver-strategy-vim "session"
+#   set -g @resurrect-strategy-vim "session"
-restore_process_strategy_option="@session-saver-strategy-"
+restore_process_strategy_option="@resurrect-strategy-"

strategies/vim_session.sh

@@ -4,7 +4,7 @@
 #
 # Restores a vim session from 'Session.vim' file, if it exists.
 # If 'Session.vim' does not exist, it falls back to invoking the original
-# command (withouth the `-S` flag).
+# command (without the `-S` flag).
 
 ORIGINAL_COMMAND="$1"
 DIRECTORY="$2"
@@ -21,7 +21,7 @@ main() {
 	if vim_session_file_exists; then
 		echo "vim -S"
 	elif original_command_contains_session_flag; then
-		# Session file does not exist, yet the orignal vim command contains
+		# Session file does not exist, yet the original vim command contains
 		# session flag `-S`. This will cause an error, so we're falling back to
 		# starting plain vim.
 		echo "vim"

video/script.md

@@ -0,0 +1,110 @@
+# Screencast script
+
+1. Intro
+========
+Let's demo tmux resurrect plugin.
+
+Tmux resurrect enables persisting tmux sessions, so it can survive the dreaded
+system restarts.
+
+The benefit is uninterrupted workflow with no configuration required.
+
+2. Working session
+==================
+Script
+------
+Let me show you what I have in this tmux demo session.
+
+First of all, I have vim open and it has a couple files loaded.
+
+Then there's a tmux window with a couple splits in various directories across
+the system.
+
+Next window contains tmux man page,
+  and then there's `htop` program.
+
+And this is just one of many projects I'm currently running.
+
+Actions
+-------
+- blank tmux window
+- vim
+  - `ls` to show open files
+- multiple pane windows (3)
+- man tmux
+- htop
+- psql
+- show a list of session
+
+3. Saving the environment
+=========================
+Script
+------
+With vanilla tmux, when I restart the computer this whole environment will be
+lost and I'll have to invest time to restore it.
+
+tmux resurrect gives you the ability to persist everything with
+prefix plus alt-s.
+
+Now tmux environment is saved and I can safely shut down tmux with a
+kill server command.
+
+Actions
+-------
+- prefix + M-s
+- :kill-server
+
+4. Restoring the environment
+============================
+Script
+------
+At this point restoring everything back is easy.
+
+I'll fire up tmux again. Notice it's completely empty.
+
+Now, I'll press prefix plus alt-r and everything will restore.
+
+Let's see how things look now.
+First of all, I'm back to the exact same window I was in when the environment
+was saved. Second - you can see the `htop` program was restored.
+
+Going back there's tmux man page
+  a window with multiple panes with the exact same layout as before
+  and vim.
+
+
+tmux resurrect takes special care of vim. By leveraging vim's sessions, it
+preserves vim's split windows, open files, even the list of files edited before.
+
+Check out the project readme for more details about special treatment for vim.
+
+That was just one of the restored tmux sessions. If I open tmux session list you
+can see all the other projects are restored as well.
+
+
+When you see all these programs running you might be concerned that this plugin
+started a lot of potentially destructive processes.
+
+For example, when you restore tmux you don't want to accidentally start backups,
+resource intensive or sensitive programs.
+
+There's no need to be worried though. By default, this plugin starts only a
+conservative list of programs like vim, less, tail, htop and similar.
+This list of programs restored by default is in the project readme. Also, you
+can easily add more programs to it.
+
+If you feel paranoid, there's an option that prevents restoring any program.
+
+Actions
+-------
+- tmux
+- prefix + M-r
+
+- open previous windows
+- in vim hit :ls
+
+- prefix + s for a list of panes
+
+5. Outro
+========
+That's it for this demo. I hope you'll find tmux resurrect useful.