Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 407 lines (257 sloc) 14.138 kb
46dcb5d @nesquena Added initial readme
nesquena authored
1 Terminitor
2 ===========
3
d5f9b4d @achiu update README contributor list and about the new directory path
authored
4 Terminitor automates your development workflow setup. Less time setting up, more time getting things done.
5
6 Upgrading Terminitor from 0.4.1 and under
7 ------------------------------------------
8
9 For those upgrading from Terminitor 0.4.1, please run:
10
11 $ terminitor update
12
13 This will move your terminitor files to the new directory located at .config/terminitor
46dcb5d @nesquena Added initial readme
nesquena authored
14
15 Installation
16 ------------
17
706e8e6 @nesquena Remove sudo (use RVM!!)
nesquena authored
18 $ gem install terminitor
5659f04 @achiu update README
authored
19 $ terminitor init
46dcb5d @nesquena Added initial readme
nesquena authored
20
8a6ad80 @achiu update README with development setup info
authored
21 Development Setup
22 ---------------------
23
24 To begin development on Terminitor, run bundler:
25
26 $ gem install bundler
27 $ bundle install
28
29 The test suite uses ([Riot](https://www.github.com/thumblemonks/riot/)).
30 to run the test run:
31
32 $ rake test
33
34 or use watchr:
35
36 $ watchr test.watchr
37
38 or if you have terminitor installed,
39
40 $ terminitor fetch achiu terminitor
41
42 this will git clone the repo and bundle install.
43
46dcb5d @nesquena Added initial readme
nesquena authored
44 Usage
45 -------
46
34abdde @nesquena Updated README with new features and contributors
nesquena authored
47 ### Creating Local Projects ###
48
73b113d @nesquena Update README to include open command and cleanup
nesquena authored
49 Using terminitor is quite easy. To define or edit a project file, simply invoke the command:
50
5659f04 @achiu update README
authored
51 $ terminitor edit foo
73b113d @nesquena Update README to include open command and cleanup
nesquena authored
52
5659f04 @achiu update README
authored
53 This will open your default editor (set through the $TERM_EDITOR or $EDITOR variable in BASH) and you can proceed to define the commands for that project with the following syntaxes:
46dcb5d @nesquena Added initial readme
nesquena authored
54
5659f04 @achiu update README
authored
55 #### YAML Syntax ( Legacy ) ####
56
d5f9b4d @achiu update README contributor list and about the new directory path
authored
57 # ~/.config/terminitor/foo.yml
46dcb5d @nesquena Added initial readme
nesquena authored
58 # you can make as many tabs as you wish...
59 # tab names are actually arbitrary at this point too.
60 ---
61 - tab1:
62 - cd ~/foo/bar
63 - gitx
64 - tab2:
8a6ad80 @achiu update README with development setup info
authored
65 - mysql -u root)
46dcb5d @nesquena Added initial readme
nesquena authored
66 - use test;
67 - show tables;
68 - tab3: echo "hello world"
69 - tab4: cd ~/baz/ && git pull
70 - tab5:
71 - cd ~/foo/project
72 - autotest
73
34abdde @nesquena Updated README with new features and contributors
nesquena authored
74 Simply define each tab and declare the commands. Note that the session for each tab is maintained, so you just declare actions here as
75 you would manually type in the terminal. Note that the title for each tab(namely tab1, tab2) are arbitrary, and can be named whatever you want.
76 They are simply placeholders for the time being for upcoming features.
46dcb5d @nesquena Added initial readme
nesquena authored
77
5659f04 @achiu update README
authored
78 To use the legacy syntax, you can invoke it with terminitor like so:
79
80 $ terminitor edit foo --syntax yml
81
74c9fa2 @achiu update README
authored
82 It is recommended that you move over to the newer Ruby DSL Syntax as it
83 provides more robust features, however terminitor will still support the older
84 YAML syntax.
85
5659f04 @achiu update README
authored
86
87 #### Ruby DSL Syntax ####
88
dfe19e5 @achiu update README
authored
89 ````ruby
90 setup 'echo "setup"' # code to run during setup
5659f04 @achiu update README
authored
91
dfe19e5 @achiu update README
authored
92 # open a tab in current window with these commands
93 tab "echo 'default'", "echo 'default tab'"
5659f04 @achiu update README
authored
94
dfe19e5 @achiu update README
authored
95 window do
96 before { run 'cd /path' } # run this command before each command.
97
98 run 'padrino start' # run in new window
74c9fa2 @achiu update README
authored
99
dfe19e5 @achiu update README
authored
100 tab "echo 'first tab'", "echo 'of window'" # create a new tab in window and run it.
101 tab "named tab" do
102 run "echo 'named tab'"
103 run "ls"
104 end
105 end
106 ````
5659f04 @achiu update README
authored
107
108 The newer Ruby DSL syntax allows for more complicated behavior such as window creation as well as setup blocks that can be executed prior loading a project.
109
110 ##### Tabs #####
111
112 to create tabs, we can simply invoke the tab command with either the command arguments like:
113
dfe19e5 @achiu update README
authored
114 ````ruby
115 tab "echo 'hi'", "gitx"
116 ````
117
5659f04 @achiu update README
authored
118 or even pass it a block:
119
dfe19e5 @achiu update README
authored
120 ````ruby
121 tab do
122 run "echo 'hi'"
123 run "mate ."
124 end
125 ````
5659f04 @achiu update README
authored
126
127 ##### Windows #####
128
129 to create windows, we can simply invoke the window command with a block containing additional commands like:
130
dfe19e5 @achiu update README
authored
131 ````ruby
132 window do
74c9fa2 @achiu update README
authored
133
dfe19e5 @achiu update README
authored
134 run "whoami" # Runs the command in the current window.
5659f04 @achiu update README
authored
135
dfe19e5 @achiu update README
authored
136 tab "echo 'hi'" # Creates another tab
137 tab "mate ." # And another
138 tab do # Last hoorah
139 run "open http://www.google.com"
140 end
141 end
142 ````
74c9fa2 @achiu update README
authored
143
144 ##### Before #####
145
146 Sometimes you'll want to create a few commands that you want to run in each tab instance. You can do that with 'before':
147
dfe19e5 @achiu update README
authored
148 ````ruby
149 before { run "cd /path" } # execute this command before other commands in the default window
150 run "whoami"
151 tab 'uptime'
74c9fa2 @achiu update README
authored
152
dfe19e5 @achiu update README
authored
153 # In this instance, "cd /path" wil be executed in the default window before 'whoami'
154 # and also in the tab before 'uptime'.
155 # You can also use this inside a specific window context:
74c9fa2 @achiu update README
authored
156
dfe19e5 @achiu update README
authored
157 window do
158 before 'cd /tmp'
159 run 'watchr test.watchr' # "cd /tmp" first than run watchr
74c9fa2 @achiu update README
authored
160
dfe19e5 @achiu update README
authored
161 tab do
162 run 'padrino start' # "cd /tmp" is ran beforehand and then padrino start is executed
163 end
164 end
165 ````
74c9fa2 @achiu update README
authored
166
167
168
5659f04 @achiu update README
authored
169 ##### Setup #####
170
171 The setup block allows you to store commands that can be ran specifically before a project and can be defined with:
172
173 the command arguments:
174
dfe19e5 @achiu update README
authored
175 ````ruby
176 setup "bundle install", "gitx"
177 ````
5659f04 @achiu update README
authored
178
179 or with a block:
180
dfe19e5 @achiu update README
authored
181 ````ruby
182 setup do
183 run "echo 'hi'"
184 run "bundle install"
185 run 'git remote add upstream git://github.com/achiu/terminitor.git'
186 end
187 ````
5659f04 @achiu update README
authored
188
189
74c9fa2 @achiu update README
authored
190 Once defined, you can invoke your projects setup with:
191
192 terminitor setup my_project
193
737eca0 @achiu update README
authored
194 ##### Settings #####
74c9fa2 @achiu update README
authored
195 _currently only available for Mac OSX Terminal_
737eca0 @achiu update README
authored
196
197 You can also set settings on each of your tabs and windows. for example, this is possible:
198
199 Open a tab with terminal settings "Grass"
200
dfe19e5 @achiu update README
authored
201 ````ruby
202 tab :name => "named tab", :settings => "Grass" do
203 run "echo 'named tab'"
204 run "ls"
205 end
206 ````
737eca0 @achiu update README
authored
207
74c9fa2 @achiu update README
authored
208 This will create a tab with a title of 'named tab' using Terminals 'Grass' setting.
209
210
737eca0 @achiu update README
authored
211 How about a window with a specific size:
212
dfe19e5 @achiu update README
authored
213 ````ruby
214 window :bounds => [10,20,300,200] do
737eca0 @achiu update README
authored
215
dfe19e5 @achiu update README
authored
216 end
217 ````ruby
737eca0 @achiu update README
authored
218
219 Currently, the following options are available:
220
221 __tabs__
222
c121960 @achiu fixed README
authored
223 * :settings - [String] Set the tab to terminal settings
224 * :selected - [Boolean] Sets whether the tab is active
225 * :miniaturized - [Boolean] Sets whether its miniaturized
226 * :visible - [Boolean] Sets whether its visible
737eca0 @achiu update README
authored
227
228
229 __windows__
230
c121960 @achiu fixed README
authored
231 * :bounds - [Array] Sets the bounds
232 * :miniaturized - [Boolean] Sets whether its miniaturized
233 * :visible - [Boolean] Sets whether its visible
737eca0 @achiu update README
authored
234
5659f04 @achiu update README
authored
235 ### Running Terminitor Projects ###
236
d5f9b4d @achiu update README contributor list and about the new directory path
authored
237 Once the project file has been declared to your satisfaction, simply execute any project defined in the `~/.config/terminitor` directory with:
46dcb5d @nesquena Added initial readme
nesquena authored
238
285d9a3 @achiu fix README
authored
239 $ terminitor start foo
46dcb5d @nesquena Added initial readme
nesquena authored
240
241 This will execute the steps and create the tabs defined and run the various options as expected. That's it. Create as many project files with as many tabs
242 as you would like and automate your workflow.
243
5659f04 @achiu update README
authored
244 ### Removing Terminitor Projects ###
245
246 If you no longer need a particular project, you can easily remove the terminitor file for the project:
1b4b70a @nesquena Added the delete command to the readme
nesquena authored
247
248 $ terminitor delete foo
5659f04 @achiu update README
authored
249
250 to remove a legacy yml syntax file you can run:
251
252 $ terminitor delete foo -s=yml
253
254
255 ### Listing Terminitor Projects ###
1b4b70a @nesquena Added the delete command to the readme
nesquena authored
256
34abdde @nesquena Updated README with new features and contributors
nesquena authored
257 You can also see a full list of available projects with:
258
259 $ terminitor list
260
5659f04 @achiu update README
authored
261 This will print out the available project files that you can execute. The list also returns whatever text you have in the first comment of each terminitor script.
34abdde @nesquena Updated README with new features and contributors
nesquena authored
262
263 ### Creating Termfile for Repo ###
264
265 In addition to creating 'local' projects which can run on your computer (and are stored in your home directory), we also
266 optionally allow you to create a `Termfile` within any directory and then you can execute this any time to setup the
267 environment for that particular project source.
268
269 For example, let's say I am in `/code/my/foo/project` directory which is
270 a Sinatra application. This application might have a `Gemfile` which includes all dependencies. You can also generate a `Termfile`
271 which contains the ideal development setup for OSX. To generate this file, invoke:
272
273 $ terminitor create
274
275 This will generate a 'Termfile' in the current project directory and open the file to be edited in the default text editor. The format
5659f04 @achiu update README
authored
276 of the file is using the new Ruby DSL as described above in the previous section. You should *note* that the project directory is automatically
1b4b70a @nesquena Added the delete command to the readme
nesquena authored
277 the working directory for each tab so you can just say `mate .` and the project directory containing the `Termfile` will open.
34abdde @nesquena Updated README with new features and contributors
nesquena authored
278
279 Now, when you or another developer clones a project, you could simply:
280
281 $ git clone git://path/to/my/foo/project.git
282 $ cd project
74c9fa2 @achiu update README
authored
283 $ terminitor setup
34abdde @nesquena Updated README with new features and contributors
nesquena authored
284 $ terminitor start
285
286 This would clone the project repo, and then install all dependencies and then launch the ideal development environment for the project. Clearly
287 this makes assumptions about the user's system setup right now, but we have some ideas on how to make this work more effectively on
288 different configurations in the future.
289
1b4b70a @nesquena Added the delete command to the readme
nesquena authored
290 In addition, you are in the project folder and you wish to remove the Termfile, you can invoke the command:
291
292 $ terminitor delete
293
294 This will clear the `Termfile` for the particular project.
295
737eca0 @achiu update README
authored
296 ### Capturing Terminal Settings with Terminitor ###
74c9fa2 @achiu update README
authored
297 _Currently Mac OSX Terminal only_
737eca0 @achiu update README
authored
298 Terminitor has the ability to also capture your terminal setup and settings simply with:
299
300 $ terminitor edit my_project --capture
301
302 this will open up a new terminitor project with the captured settings for you to continuing modifying as you see fit.
303
5659f04 @achiu update README
authored
304
305 ### Fetching Github Projects with Terminitor ###
306
74c9fa2 @achiu update README
authored
307 Terminitor can also fetch code repositories off Github. This will have terminitor clone the repo into the current directory:
5659f04 @achiu update README
authored
308
309 $ terminitor fetch achiu terminitor
74c9fa2 @achiu update README
authored
310
5659f04 @achiu update README
authored
311 After the repo has been fetched, terminitor will go ahead and run the setup block from the Termfile included in the repository. In the event you wouldn't want the setup block to be executed, simply set setup to false:
312
313 $ terminitor fetch achiu terminitor --setup=false
314
315 Some notes. Terminitor's fetch command is dependent on the ([github-gem](http://github.com/defunkt/github-gem)) at the current moment. It will try to fetch the repository with read/write access first if you have rights, if not, it will default to git read only. Happy fetching!
316
317
318 Cores
319 -----
320
321 Cores allow Terminitor to operate on a variety of platforms. They abstract the general behavior that terminitor needs to run the commands. Each core would inherit from an ([AbstractCore](http://github.com/achiu/terminitor/blob/master/lib/terminitor/abstract_core.rb)) and define the needed methods. At the moment the following Cores are supported:
322
323 * MacCore - Mac OS X Terminal
324 * KonsoleCore - KDE Konsole
0b88fea @achiu update README with fixes and contributors
authored
325 * TerminatorCore - [Terminator](http://www.tenshu.net/terminator/)
179dff5 @achiu update README for iTerm
authored
326 * ITermCore - Mac OS X iTerm
5659f04 @achiu update README
authored
327
328 Feel free to contribute more cores so that Terminitor can support your terminal of choice :)
329
330
46dcb5d @nesquena Added initial readme
nesquena authored
331 Limitations
332 -----------
333
5659f04 @achiu update README
authored
334 #### MacCore ####
46dcb5d @nesquena Added initial readme
nesquena authored
335
5659f04 @achiu update README
authored
336 Right now the Mac OS X Terminal tabs are created by invoking keystrokes which means there are limitations with the terminal being in
737eca0 @achiu update README
authored
337 focus during execution of these commands. Obviously the long term goal is to solve this issue as well but in all honesty, this solution works well enough most of the time.
34abdde @nesquena Updated README with new features and contributors
nesquena authored
338
179dff5 @achiu update README for iTerm
authored
339
340 #### ITermCore ####
341
342 Currently the iTerm Core only provides basic functionality such as opening tabs, windows, and executing commands within them. The capture
343 and settings functionality will be integrated soon.
344
345
5659f04 @achiu update README
authored
346 #### Fetching ####
347
8dac74b @achiu update README
authored
348 The fetch task only pulls off Github repositories at the moment. Later on, this functionality will be extended to non github repository.
5659f04 @achiu update README
authored
349
737eca0 @achiu update README
authored
350
351 #### Settings and Captures ####
352
353 This feature is currently only available in Mac OS X at the moment.
354
355
a27d3e3 @ilkka Add note about new core and its requirements to README
ilkka authored
356 #### Terminator support ####
357
358 This feature currently requires the "xdotool" utility to be installed and in
359 the search path. The xdotool homepage is
360 http://www.semicomplete.com/blog/projects/xdotool/.
361
362
d5f9b4d @achiu update README contributor list and about the new directory path
authored
363 #### Windows suppport ####
364
365 Windows support is currently limited to plain cmd.exe. It is also
366 limited to only creating new windows, as cmd.exe does not support tabs.
367
368
00e3ac8 @nesquena Updated readme with authors.
nesquena authored
369 Authors
370 -------
371
34abdde @nesquena Updated README with new features and contributors
nesquena authored
372 The core code was adapted before by Nathan Esquenazi and Thomas Shafer.
373 In September 2010, Arthur Chiu and Nathan Esquenazi gemified and released this to gemcutter.
374
375 Contributors
376 -------------
377
378 Thanks to the following people for their contributions so far:
379
23ba406 @achiu fix/update README
authored
380 * Pat George ([pcg79](https://github.com/pcg79)) for contributing a patch for when a project is not found.
0b88fea @achiu update README with fixes and contributors
authored
381 * Tim Gossett ([[MrGossett](https://github.com/MrGossett)) for a patch to fix comment reading
23ba406 @achiu fix/update README
authored
382 * Flavio Castelli ([flavio](https://github.com/flavio)) for contributing Konsole(KDE) core.
383 * Alexey Kuleshov ([kulesa](https://github.com/kulesa)) for contributing the terminal settings and terminal settings capture functionality
384 * Arthur Gunn ([gunn](https://github.com/gunn)) for contributing a path to support tab syntax and load path.
b42f2b1 @achiu update README
authored
385 * Elliot Winkler ([mcmire](https://github.com/mcmire)) for adding 1.8.6 compatiblity and ensuring tabs open in order and fixing named tabs
19d88e7 @achiu update README with contributors
authored
386 * Justin Hilemen ([bobthecow](https://github.com/bobthecow)) for fixing the list command to remove the term extensions.
0b88fea @achiu update README with fixes and contributors
authored
387 * Dave Perrett ([recurser](https://github.com/recurser)) for adding basic iTerm support.
388 * Ilkka Laukkanen ([ilkka](https://github.com/achiu/terminitor/commits/master?author=ilkka)) for Terminator core and other fixes
389 * Elia Schito ([elia](https://github.com/achiu/terminitor/commits/master?author=elia)) for patch to allow usage of "&" for background operations
3f5a5d5 @achiu update README with contributors
authored
390 * Dotan J. Nahum ([jondot](https://github.com/jondot)) for adding windows(cmd.exe) support
391 * Kyriacos Souroullas ([kyriacos](https://github.com/kyriacos) For removing params to support generic commands
392 * Jerry Cheung ([jch](https://github.com/jch)) For adding ignore for emac backups
d9a334a @achiu update README
authored
393
46dcb5d @nesquena Added initial readme
nesquena authored
394 Acknowledgements
395 -----------------
396
b8c9ecf @nesquena Added the note about Jeff Emminger being the original developer of th…
nesquena authored
397
398
399 The core terminal scripting code was initially developed by [Jeff Emminger](http://workingwithrails.com/person/2412-jeff-emminger) years ago. The original introduction was made on the [ELCTech Blog](http://blog.elctech.com/2008/01/16/script-terminal-with-terminit/) and a lot of that code was adapted from [Scripting the Terminal in Leopard](http://onrails.org/articles/2007/11/28/scripting-the-leopard-terminal).
400
401 This was a great start and made terminal automation easy. However, the repository died long ago, and we had continued using the code for a while.
402 Finally, we decided the time had come to release this code back to the world as a gem. Thanks to ELC for creating the original source for this project.
73b113d @nesquena Update README to include open command and cleanup
nesquena authored
403
404 Also, we didn't take any code from [Project](http://github.com/joshnesbitt/project) by Josh but that project did inspire us to setup terminit
405 as a gem. Basically, project is a great gem but there were a couple issues with the fact that the terminal doesn't save the session state in some cases.
74c9fa2 @achiu update README
authored
406 I had already been using terminit for years so we decided to package this up for easy use.
Something went wrong with that request. Please try again.