Fork me on GitHub

screen-session

About | News | Documentation | Installation | Screenshots | Feedback | Download

Documentation

screen-session is a collection of utilities for GNU Screen.

Usage:   screen-session [mode] [options]

Help:    scs help [mode]

Options supported by all tools:
    -S [target] - target Screen session name
    -h  --help  - print detailed mode's help

Environment variables:
    SCREENBIN   - GNU Screen executable path
    PYTHONBIN   - Python interpreter path
    STY         - target Screen session name

Session saver modes:

load Load saved session from a file.
ls List saved sessions.
other Auxiliary mode, used mainly by screen-session-primer.
save Save GNU Screen and VIM sessions to a file.

Tools:

dump Print informations about windows in session (MRU order by default).
group Move windows to a group.
kill Kill last process started in a window.
kill-group Recursively kill groups and windows inside.
kill-zombie Kill all zombie windows in session. Optionally specify target groups.
layout-checkpoint Record a snapshot of the current layout.
layout-history Display saved snapshots of the current layout.
layout-redo Load a snapshot of the current layout,
layout-undo Load a snapshot of the current layout,
layout-zoom Zoom into and out of a region. Intended to replace ":only" command.
layoutlist Displays a browseable list of layouts. There are two list creation algorithms.
manager Sessions manager for GNU Screen with preview in a split window.
name Get or set the sessionname.
nest Nest a layout in the current region.
new-window Start a new Screen window with the same working directory as the current window.
regions Display a number in each region.
renumber Renumber windows to fill the gaps.
subwindows Print windows contained in groups.

# load

Usage: screen-session load [-S sessionname] [options] [source_savefile]

Load saved session from a file.
Howto: http://adb.cba.pl/gnu-screen-tips-page-my.html#howto-screen-session

Options:
-x --exact
    load session with the same window numbers, move existing windows,
    to OTHER_WINDOWS group and delete existing layouts
-X --exact-kill
    same as exact, but also kill all existing windows
-F --force-start  [windows]
    a comma separated list of windows which will start programs immediately,
    using keyword "all" causes all loaded windows to start their subprograms
    without waiting for user's confirmation
-y --no-layout
    disable layout loading
-n --no-group-wrap
    do not wrap windows in RESTORE_* or OTHER_WINDOWS_* groups
-m --mru
    enable restoring of the Most Recently Used order of windows
-l --log  [file]
    output to a file instead of stdout and stderr
-d --dir  [directory = $HOME/.screen-sessions]
    directory holding saved sessions

Examples:
#1# restore mysavedsession inside Screen named SESSIONNAME
screen-session load -S SESSIONNAME --exact mysavedsession
#2# load the last saved session inside the current Screen session
scs load
#3# load the last saved session with exactly the same window numbers
scs load --exact
#4# load inside the current session without layouts and start all subprograms
scs load --no-layout --force-start all
#5# load the last saved session into a new Screen
screen -m scs load --exact-kill

See also: save, ls, other

# ls

Usage: screen-session save [-S sessionname] [options] [savefile_filter]

List saved sessions.

Options:
-l --log  [file]
    output to a file instead of stdout and stderr
-d --dir  [directory = $HOME/.screen-sessions]
    directory holding saved sessions

See also: save, load, other

# other

Usage: screen-session other [options]

Auxiliary mode, used mainly by screen-session-primer.

Options:
--pack [target]
    archive unpacked savefile ( which must be accessible from --dir )
--unpack [savefile]
    unpack savefile to /tmp/screen-session-$USER
-l --log  [file]
    output to a file instead of stdout and stderr
-d --dir  [directory = $HOME/.screen-sessions]
    directory holding saved sessions

See also: save, load, ls

# save

Usage: screen-session save [-S sessionname] [options] [target_savefile]
       :bind S at 0 exec screen -mdc /dev/null screen-session save -fS $PID.$STY

Save GNU Screen and VIM sessions to a file.
Howto: http://adb.cba.pl/gnu-screen-tips-page-my.html#howto-screen-session

Options:
-f --force
    force saving even if a savefile with the same name already exists
-e --exclude  [windows]
    a comma separated list of windows to be ignored during saving,
    if a window is a group all nested windows are also included
-L --exclude-layout  [layouts]
    a comma separated list of layouts to be ignored during saving,
-H --no-scroll  [windows]
    a comma separated list of windows which scrollbacks will be ignored,
    if a window is a group all nested windows are also included,
    using keyword "all" affects all windows
-y --no-layout
    disable layout saving
-V --no-vim
    disable vim session saving
-l --log [file]
    output to a file instead of stdout and stderr
-d --dir  [directory = $HOME/.screen-sessions]
    directory holding saved sessions

Examples:
#1# save Screen named SESSIONNAME as mysavedsession
screen-session save -S SESSIONNAME mysavedsession
#2# save the current session, force overwrite of old savefiles
scs save --force
#3# save the current session without layouts and without window "SECURE" scroll
scs save --no-layout --no-scroll SECURE
#4# run session saver after 3 minutes of inactivity
:idle 180 at 0 exec scs save --force --log /dev/null
#5# an alternative binding
bind S eval 'colon' 'stuff "at 0 exec screen -mdc /dev/null scs save -fS \"$PID.$STY\""'

See also: load, ls, other

# dump

Usage: screen-session dump [options] [window_ids]
       scs d

Print informations about windows in session (MRU order by default).
A dot "." selects current window, 2 dots ".."  select current group.

Options:
-P   - do not show pid data
-r   - reverse the output
-s   - sort by window number

# group

Usage: screen-session group [options] [GROUP] [windows]
       scs g
       :bind G eval "colon" "stuff \"at 0 exec scs group \""

Move windows to a group.
If no windows given, move the current window.

# kill

Usage: screen-session kill [options] [signal=TERM] [window=current]
       scs K

Kill last process started in a window.
Useful for closing random emacs/vim instances and hung up ssh clients.
WARNING: sending KILL signal to the current window may crash Screen.

Options:
-t [tty device]

Example:
scs kill TERM 3


# kill-group

Usage: screen-session kill-group [options] [groupNum0] [groupNum..]
       scs kg

Recursively kill groups and windows inside.
Accepts titles and window numbers as arguments.
A dot "." selects current window, 2 dots ".."  select current group.
Take extra care with this command.

# kill-zombie

Usage: screen-session kill-zombie [options] [group_ids]
       scs kz

Kill all zombie windows in session. Optionally specify target groups.

# layout-checkpoint

Usage: screen-session layout-checkpoint [options]
       scs lc

Record a snapshot of the current layout.
Either run it frequently or integrate it with keybindings.

Example:
    bind S eval "split" "at 0 exec screen-session layout-checkpoint"

See also: layoutlist, layout-undo, layout-redo, layout-history

# layout-history

Usage: screen-session layout-history [options]
       scs lh

Display saved snapshots of the current layout.

See also: layout-checkpoint, layout-undo, layout-redo

# layout-redo

Usage: screen-session layout-redo [options] [step = 1]
       scs lr

Load a snapshot of the current layout,
step = 0 indicates the current snapshot, step = 1 the previous snapshot, ...

See also: layout-checkpoint, layout-undo, layout-history

# layout-undo

Usage: screen-session layout-undo [options] [step = 1]
       scs lu

Load a snapshot of the current layout,
step = 0 indicates the current snapshot, step = 1 the previous snapshot, ...

See also: layout-checkpoint, layout-redo, layout-history

# layout-zoom

Usage: screen-session layout-zoom [options]
       scs lz
       :bind o at 0 exec scs layout-zoom

Zoom into and out of a region. Intended to replace ":only" command.
Requires an active layout. Inspired by ZoomWin Vim plugin:
http://www.vim.org/scripts/script.php?script_id=508

See also: layout-checkpoint, layout-undo, layout-redo

# layoutlist

Usage: screen-session layoutlist [options] [HEIGHT]
       scs ll
       :bind l at 0 exec scs layoutlist -l -c 20

Displays a browseable list of layouts. There are two list creation algorithms.
If HEIGHT != 0, an alternative list creation algorithm is used. Layout numbers
are modulo divided by HEIGHT and the reminder determines their Y position.
This tool comes handy after raising the maximum number of layouts
(see ":maxlay" Screen command).

Options:
-a [min_len=2]  - minimum matching charecters for auto highlight,
                  min_len = 0 disables auto highlight
-c              - do not terminate layoutlist after selecting a layout
                  or reselect a running layoutlist, best used with "-l" option,
                  there should be running only one layoutlist started with "-c"
                  per session
-l              - create a temporary layout and window for layoutlist
-M              - select previous layout and exit
-p              - run layout-checkpoint before activating layoutlist
-w              - create a temporary window for layoutlist
-t [width=11]   - set title width

Keys:
?               - display help
ENTER           - confirm / select
ARROWS and hjkl - movement
/ or SPACE      - start searching layout titles
n and p         - next / previous search result
NUMBER          - move to a layout
r or C-c or C-l - refresh the layout list
m or a          - toggle MRU view,
v               - toggle search/autohighlight results view
o               - toggle current and selected layouts
q               - quit / select previous layout
Q               - force quit if "-c" option was used

Note: If you are using -c and -l options and layoutlist stopped working
      properly, then delete the temporary directory:
      /tmp/screen-session-$USER/___layoutlist

See also: layout-checkpoint, layout-zoom

# manager

Usage: screen-session manager [account@host]
       scs m

Sessions manager for GNU Screen with preview in a split window.
Requires python 2.5+

KEYS:
CTRL + g  - default escape key
ALT + t   - toggle between regions
ALT + e   - step into a selected session
ALT + q   - quit
Alt + w   - wipe

COMMANDS:
? or h          - display help
q[uit]          - exit session manager
e[nter]         - enter into a session
a[ttach] [name] - attach and select
d[etach] [name] - detach and deselect
n[ame] [name]   - rename
s[creen] [args] - create session
save [output]   - save session
w[ipe]          - wipe dead sessions
restart         - restart session manager
r[efresh]       - refresh session list
l[ayout]        - toggle layout
kill K          - kill selected session


# name

Usage: screen-session name [options] [new_sessionname]
       scs n

Get or set the sessionname.

# nest

Usage: screen-session nest-layout [options] [TARGET_LAYOUT]
       scs nl
       :bind N eval "colon" "stuff \"at 0 exec scs nest-layout \""

Nest a layout in the current region.

# new-window

Usage: screen-session new-window [options] [program]
       scs new
       scs nw
       :bind c eval "colon" "stuff \"at 0 exec scs new-window \""

Start a new Screen window with the same working directory as the current window.

Options:
-d [directory] - specify the new window working directory
-n [win_num]   - set the new window number
-N             - automatically set the new window number to (current number + 1)

# regions

Usage: screen-session regions [options]
       scs r
       :bind X at 0 exec scs regions

Display a number in each region.
Allows selecting, swapping and rotating. Inspired by tmux display-panes.
Requires an active layout.

Keys:
goto region  - number and [g] or ['] or [space]
swap regions - number and [s]
rotate left  - number and [l]
rotate right - number and [r]

reverse goto region     - number and [G]
swap regions and select - number and [S]
rotate left  and select - number and [L]
rotate right and select - number and [R]

Note: regions tool may appear late if there is no hardstatus line

# renumber

Usage: screen-session renumber [options]

Renumber windows to fill the gaps.

# subwindows

Usage: screen-session subwindows [groupids or titles]
       scs sw

Print windows contained in groups.
A dot "." selects current window, 2 dots ".."  select current group.

HTML 4.01 Transitional  Last modified: October 31, 2011