Skip to content

Commit 314e34c

Browse files
committed
docs: Convert README to markdown
pandoc 2.14, prettier 2.3.1, myst-parser 0.15.0 pandoc --from rst --to gfm README.rst --markdown-headings=atx | \ sed s/"<"/"\("/g | sed s/">"/"\)"/g | \ sed s/"- "/"- "/g > tmp; mv tmp README.md prettier --parser=markdown -w README.md Inside of docs/index.md: ```{include} ../README.md ```
1 parent 08a8d77 commit 314e34c

File tree

3 files changed

+252
-298
lines changed

3 files changed

+252
-298
lines changed

README.md

Lines changed: 251 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
tmuxp, tmux session manager. built on
2+
[libtmux](https://github.com/tmux-python/libtmux).
3+
4+
[![Python Package](https://img.shields.io/pypi/v/tmuxp.svg)](http://badge.fury.io/py/tmuxp)
5+
[![Docs](https://github.com/tmux-python/tmuxp/workflows/Publish%20Docs/badge.svg)](https://github.com/tmux-python/tmuxp/actions?query=workflow%3A%22Publish+Docs%22)
6+
[![Build status](https://github.com/tmux-python/tmuxp/workflows/tests/badge.svg)](https://github.com/tmux-python/tmuxp/actions?query=workflow%3A%22tests%22)
7+
[![Code Coverage](https://codecov.io/gh/tmux-python/tmuxp/branch/master/graph/badge.svg)](https://codecov.io/gh/tmux-python/tmuxp)
8+
![License](https://img.shields.io/github/license/tmux-python/tmuxp.svg)
9+
10+
**We need help!** tmuxp is a trusted session manager for tmux. If you
11+
could lend your time to helping answer issues and QA pull requests,
12+
please do! See [issue
13+
#290](https://github.com/tmux-python/tmuxp/issues/290)!
14+
15+
**New to tmux?** [The Tao of tmux](https://leanpub.com/the-tao-of-tmux)
16+
is available on Leanpub and [Amazon Kindle](http://amzn.to/2gPfRhC).
17+
Read and browse the book for free [on the
18+
web](https://leanpub.com/the-tao-of-tmux/read).
19+
20+
# Installation
21+
22+
## Pip
23+
24+
```shell
25+
$ pip install --user tmuxp
26+
```
27+
28+
## Homebrew
29+
30+
```shell
31+
$ brew install tmuxp
32+
```
33+
34+
# Load a tmux session
35+
36+
Load tmux sessions via json and YAML,
37+
[tmuxinator](https://github.com/aziz/tmuxinator) and
38+
[teamocil](https://github.com/remiprev/teamocil) style.
39+
40+
```yaml
41+
session_name: 4-pane-split
42+
windows:
43+
- window_name: dev window
44+
layout: tiled
45+
shell_command_before:
46+
- cd ~/ # run as a first command in all panes
47+
panes:
48+
- shell_command: # pane no. 1
49+
- cd /var/log # run multiple commands in this pane
50+
- ls -al | grep \.log
51+
- echo second pane # pane no. 2
52+
- echo third pane # pane no. 3
53+
- echo forth pane # pane no. 4
54+
```
55+
56+
Save as _mysession.yaml_, and load:
57+
58+
```sh
59+
$ tmuxp load ./mysession.yaml
60+
```
61+
62+
Projects with _.tmuxp.yaml_ or _.tmuxp.json_ load via directory:
63+
64+
```sh
65+
$ tmuxp load path/to/my/project/
66+
```
67+
68+
Load multiple at once (in bg, offer to attach last):
69+
70+
```sh
71+
$ tmuxp load mysession ./another/project/
72+
```
73+
74+
Name a session:
75+
76+
```bash
77+
$ tmxup load -s session_name ./mysession.yaml
78+
```
79+
80+
[simple](http://tmuxp.git-pull.com/examples.html#short-hand-inline) and
81+
[very
82+
elaborate](http://tmuxp.git-pull.com/examples.html#super-advanced-dev-environment)
83+
config examples
84+
85+
# User-level configurations
86+
87+
tmuxp checks for configs in user directories:
88+
89+
- `$TMUXP_CONFIGDIR`, if set
90+
- `$XDG_CONFIG_HOME`, usually _$HOME/.config/tmuxp/_
91+
- `$HOME/.tmuxp/`
92+
93+
Load your tmuxp config from anywhere by using the filename, assuming
94+
_\~/.config/tmuxp/mysession.yaml_ (or _.json_):
95+
96+
```sh
97+
$ tmuxp load mysession
98+
```
99+
100+
See [author's tmuxp configs](https://github.com/tony/tmuxp-config) and
101+
the projects'
102+
[tmuxp.yaml](https://github.com/tmux-python/tmuxp/blob/master/.tmuxp.yaml).
103+
104+
# Shell
105+
106+
_New in 1.6.0_:
107+
108+
`tmuxp shell` launches into a python console preloaded with the attached
109+
server, session, and window in
110+
[libtmux](https://github.com/tmux-python/libtmux) objects.
111+
112+
```shell
113+
$ tmuxp shell
114+
115+
(Pdb) server
116+
<libtmux.server.Server object at 0x7f7dc8e69d10>
117+
(Pdb) server.sessions
118+
[Session($1 your_project)]
119+
(Pdb) session
120+
Session($1 your_project)
121+
(Pdb) session.name
122+
'your_project'
123+
(Pdb) window
124+
Window(@3 1:your_window, Session($1 your_project))
125+
(Pdb) window.name
126+
'your_window'
127+
(Pdb) window.panes
128+
[Pane(%6 Window(@3 1:your_window, Session($1 your_project)))
129+
(Pdb) pane
130+
Pane(%6 Window(@3 1:your_window, Session($1 your_project))
131+
```
132+
133+
Python 3.7+ supports [PEP
134+
553](https://www.python.org/dev/peps/pep-0553/) `breakpoint()`
135+
(including `PYTHONBREAKPOINT`). Also supports direct commands via `-c`:
136+
137+
```shell
138+
$ tmuxp shell -c 'print(window.name)'
139+
my_window
140+
141+
$ tmuxp shell -c 'print(window.name.upper())'
142+
MY_WINDOW
143+
```
144+
145+
Read more on [tmuxp shell](https://tmuxp.git-pull.com/cli.html#shell) in
146+
the CLI docs.
147+
148+
# Pre-load hook
149+
150+
Run custom startup scripts (such as installing project dependencies
151+
before loading tmux. See the
152+
[bootstrap_env.py](https://github.com/tmux-python/tmuxp/blob/master/bootstrap_env.py)
153+
and
154+
[before_script](http://tmuxp.git-pull.com/examples.html#bootstrap-project-before-launch)
155+
example
156+
157+
# Load in detached state
158+
159+
You can also load sessions in the background by passing `-d` flag
160+
161+
# Screenshot
162+
163+
<img src="https://raw.githubusercontent.com/tmux-python/tmuxp/master/docs/_static/tmuxp-demo.gif" class="align-center" style="width:45.0%" alt="image" />
164+
165+
# Freeze a tmux session
166+
167+
Snapshot your tmux layout, pane paths, and window/session names.
168+
169+
```sh
170+
$ tmuxp freeze session-name
171+
```
172+
173+
See more about [freezing
174+
tmux](http://tmuxp.git-pull.com/cli.html#freeze-sessions) sessions.
175+
176+
# Convert a session file
177+
178+
Convert a session file from yaml to json and vice versa.
179+
180+
```sh
181+
$ tmuxp convert filename
182+
```
183+
184+
This will prompt you for confirmation and shows you the new file that is
185+
going to be written.
186+
187+
You can auto confirm the prompt. In this case no preview will be shown.
188+
189+
```sh
190+
$ tmuxp convert -y filename
191+
$ tmuxp convert --yes filename
192+
```
193+
194+
# Plugin System
195+
196+
tmuxp has a plugin system to allow for custom behavior. See more about
197+
the [Plugin System](http://tmuxp.git-pull.com/plugin_system.html).
198+
199+
# Debugging Helpers
200+
201+
The `load` command provides a way to log output to a log file for
202+
debugging purposes.
203+
204+
```sh
205+
$ tmuxp load --log-file <log-file-name> .
206+
```
207+
208+
Collect system info to submit with a Github issue:
209+
210+
```sh
211+
$ tmuxp debug-info
212+
------------------
213+
environment:
214+
system: Linux
215+
arch: x86_64
216+
217+
# ... so on
218+
```
219+
220+
# Docs / Reading material
221+
222+
See the [Quickstart](http://tmuxp.git-pull.com/quickstart.html).
223+
224+
[Documentation](http://tmuxp.git-pull.com) homepage (also in
225+
[中文](http://tmuxp-zh.rtfd.org/))
226+
227+
Want to learn more about tmux itself? [Read The Tao of Tmux
228+
online](http://tmuxp.git-pull.com/about_tmux.html).
229+
230+
# Donations
231+
232+
Your donations fund development of new features, testing and support.
233+
Your money will go directly to maintenance and development of the
234+
project. If you are an individual, feel free to give whatever feels
235+
right for the value you get out of the project.
236+
237+
See donation options at <https://git-pull.com/support.html>.
238+
239+
# Project details
240+
241+
- tmux support: 1.8, 1.9a, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
242+
- python support: >= 3.6, pypy, pypy3
243+
- Source: <https://github.com/tmux-python/tmuxp>
244+
- Docs: <https://tmuxp.git-pull.com>
245+
- API: <https://tmuxp.git-pull.com/api.html>
246+
- Changelog: <https://tmuxp.git-pull.com/history.html>
247+
- Issues: <https://github.com/tmux-python/tmuxp/issues>
248+
- Test Coverage: <https://codecov.io/gh/tmux-python/tmuxp>
249+
- pypi: <https://pypi.python.org/pypi/tmuxp>
250+
- Open Hub: <https://www.openhub.net/p/tmuxp-python>
251+
- License: [MIT](http://opensource.org/licenses/MIT).

0 commit comments

Comments
 (0)