Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 351 lines (214 sloc) 12.358 kB
46dcb5d @nesquena Added initial readme
nesquena authored
1 Terminitor
2 ===========
3
74c9fa2 @achiu update README
authored
4 Terminitor automates your development workflow setup. Less time setting up, more time getting things done.
46dcb5d @nesquena Added initial readme
nesquena authored
5
6 Installation
7 ------------
8
706e8e6 @nesquena Remove sudo (use RVM!!)
nesquena authored
9 $ gem install terminitor
5659f04 @achiu update README
authored
10 $ terminitor init
46dcb5d @nesquena Added initial readme
nesquena authored
11
8a6ad80 @achiu update README with development setup info
authored
12 Development Setup
13 ---------------------
14
15 To begin development on Terminitor, run bundler:
16
17 $ gem install bundler
18 $ bundle install
19
20 The test suite uses ([Riot](https://www.github.com/thumblemonks/riot/)).
21 to run the test run:
22
23 $ rake test
24
25 or use watchr:
26
27 $ watchr test.watchr
28
29 or if you have terminitor installed,
30
31 $ terminitor fetch achiu terminitor
32
33 this will git clone the repo and bundle install.
34
46dcb5d @nesquena Added initial readme
nesquena authored
35 Usage
36 -------
37
34abdde @nesquena Updated README with new features and contributors
nesquena authored
38 ### Creating Local Projects ###
39
73b113d @nesquena Update README to include open command and cleanup
nesquena authored
40 Using terminitor is quite easy. To define or edit a project file, simply invoke the command:
41
5659f04 @achiu update README
authored
42 $ terminitor edit foo
73b113d @nesquena Update README to include open command and cleanup
nesquena authored
43
5659f04 @achiu update README
authored
44 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
45
5659f04 @achiu update README
authored
46 #### YAML Syntax ( Legacy ) ####
47
34abdde @nesquena Updated README with new features and contributors
nesquena authored
48 # ~/.terminitor/foo.yml
46dcb5d @nesquena Added initial readme
nesquena authored
49 # you can make as many tabs as you wish...
50 # tab names are actually arbitrary at this point too.
51 ---
52 - tab1:
53 - cd ~/foo/bar
54 - gitx
55 - tab2:
8a6ad80 @achiu update README with development setup info
authored
56 - mysql -u root)
46dcb5d @nesquena Added initial readme
nesquena authored
57 - use test;
58 - show tables;
59 - tab3: echo "hello world"
60 - tab4: cd ~/baz/ && git pull
61 - tab5:
62 - cd ~/foo/project
63 - autotest
64
34abdde @nesquena Updated README with new features and contributors
nesquena authored
65 Simply define each tab and declare the commands. Note that the session for each tab is maintained, so you just declare actions here as
66 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.
67 They are simply placeholders for the time being for upcoming features.
46dcb5d @nesquena Added initial readme
nesquena authored
68
5659f04 @achiu update README
authored
69 To use the legacy syntax, you can invoke it with terminitor like so:
70
71 $ terminitor edit foo --syntax yml
72
74c9fa2 @achiu update README
authored
73 It is recommended that you move over to the newer Ruby DSL Syntax as it
74 provides more robust features, however terminitor will still support the older
75 YAML syntax.
76
5659f04 @achiu update README
authored
77
78 #### Ruby DSL Syntax ####
79
74c9fa2 @achiu update README
authored
80 setup 'echo "setup"' # code to run during setup
5659f04 @achiu update README
authored
81
74c9fa2 @achiu update README
authored
82 # open a tab in current window with these commands
5659f04 @achiu update README
authored
83 tab "echo 'default'", "echo 'default tab'"
84
85 window do
74c9fa2 @achiu update README
authored
86 before { run 'cd /path' } # run this command before each command.
87
88 run 'padrino start' # run in new window
89
90 tab "echo 'first tab'", "echo 'of window'" # create a new tab in window and run it.
5659f04 @achiu update README
authored
91 tab "named tab" do
92 run "echo 'named tab'"
93 run "ls"
94 end
95 end
96
97 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.
98
99 ##### Tabs #####
100
101 to create tabs, we can simply invoke the tab command with either the command arguments like:
102
103 tab "echo 'hi'", "gitx"
104
105 or even pass it a block:
106
107 tab do
108 run "echo 'hi'"
109 run "mate ."
110 end
111
112 ##### Windows #####
113
114 to create windows, we can simply invoke the window command with a block containing additional commands like:
115
116 window do
74c9fa2 @achiu update README
authored
117
118 run "whoami" # Runs the command in the current window.
119
120 tab "echo 'hi'" # Creates another tab
121 tab "mate ." # And another
122 tab do # Last hoorah
5659f04 @achiu update README
authored
123 run "open http://www.google.com"
124 end
125 end
126
74c9fa2 @achiu update README
authored
127
128 ##### Before #####
129
130 Sometimes you'll want to create a few commands that you want to run in each tab instance. You can do that with 'before':
131
132 before { run "cd /path" } # execute this command before other commands in the default window
133 run "whoami"
134 tab 'uptime'
135
136 # In this instance, "cd /path" wil be executed in the default window before 'whoami'
137 # and also in the tab before 'uptime'.
138 # You can also use this inside a specific window context:
139
140 window do
141 before 'cd /tmp'
142 run 'watchr test.watchr' # "cd /tmp" first than run watchr
143
144 tab do
145 run 'padrino start' # "cd /tmp" is ran beforehand and then padrino start is executed
146 end
147 end
148
149
150
5659f04 @achiu update README
authored
151 ##### Setup #####
152
153 The setup block allows you to store commands that can be ran specifically before a project and can be defined with:
154
155 the command arguments:
156
157 setup "bundle install", "gitx"
158
159 or with a block:
160
161 setup do
162 run "echo 'hi'"
163 run "bundle install"
74c9fa2 @achiu update README
authored
164 run 'git remote add upstream git://github.com/achiu/terminitor.git'
5659f04 @achiu update README
authored
165 end
166
167
74c9fa2 @achiu update README
authored
168 Once defined, you can invoke your projects setup with:
169
170 terminitor setup my_project
171
737eca0 @achiu update README
authored
172 ##### Settings #####
74c9fa2 @achiu update README
authored
173 _currently only available for Mac OSX Terminal_
737eca0 @achiu update README
authored
174
175 You can also set settings on each of your tabs and windows. for example, this is possible:
176
177 Open a tab with terminal settings "Grass"
178
74c9fa2 @achiu update README
authored
179 tab :name => "named tab", :settings => "Grass" do
737eca0 @achiu update README
authored
180 run "echo 'named tab'"
181 run "ls"
182 end
183
74c9fa2 @achiu update README
authored
184 This will create a tab with a title of 'named tab' using Terminals 'Grass' setting.
185
186
737eca0 @achiu update README
authored
187 How about a window with a specific size:
188
7e4dca5 @achiu :bound => :bounds
authored
189 window :bounds => [10,20,300,200] do
737eca0 @achiu update README
authored
190
191 end
192
193 Currently, the following options are available:
194
195 __tabs__
196
c121960 @achiu fixed README
authored
197 * :settings - [String] Set the tab to terminal settings
198 * :selected - [Boolean] Sets whether the tab is active
199 * :miniaturized - [Boolean] Sets whether its miniaturized
200 * :visible - [Boolean] Sets whether its visible
737eca0 @achiu update README
authored
201
202
203 __windows__
204
c121960 @achiu fixed README
authored
205 * :bounds - [Array] Sets the bounds
206 * :miniaturized - [Boolean] Sets whether its miniaturized
207 * :visible - [Boolean] Sets whether its visible
737eca0 @achiu update README
authored
208
5659f04 @achiu update README
authored
209 ### Running Terminitor Projects ###
210
f1871bd @nesquena Minor path fix to README
nesquena authored
211 Once the project file has been declared to your satisfaction, simply execute any project defined in the `~/.terminitor` directory with:
46dcb5d @nesquena Added initial readme
nesquena authored
212
285d9a3 @achiu fix README
authored
213 $ terminitor start foo
46dcb5d @nesquena Added initial readme
nesquena authored
214
215 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
216 as you would like and automate your workflow.
217
5659f04 @achiu update README
authored
218 ### Removing Terminitor Projects ###
219
220 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
221
222 $ terminitor delete foo
5659f04 @achiu update README
authored
223
224 to remove a legacy yml syntax file you can run:
225
226 $ terminitor delete foo -s=yml
227
228
229 ### Listing Terminitor Projects ###
1b4b70a @nesquena Added the delete command to the readme
nesquena authored
230
34abdde @nesquena Updated README with new features and contributors
nesquena authored
231 You can also see a full list of available projects with:
232
233 $ terminitor list
234
5659f04 @achiu update README
authored
235 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
236
237 ### Creating Termfile for Repo ###
238
239 In addition to creating 'local' projects which can run on your computer (and are stored in your home directory), we also
240 optionally allow you to create a `Termfile` within any directory and then you can execute this any time to setup the
241 environment for that particular project source.
242
243 For example, let's say I am in `/code/my/foo/project` directory which is
244 a Sinatra application. This application might have a `Gemfile` which includes all dependencies. You can also generate a `Termfile`
245 which contains the ideal development setup for OSX. To generate this file, invoke:
246
247 $ terminitor create
248
249 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
250 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
251 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
252
253 Now, when you or another developer clones a project, you could simply:
254
255 $ git clone git://path/to/my/foo/project.git
256 $ cd project
74c9fa2 @achiu update README
authored
257 $ terminitor setup
34abdde @nesquena Updated README with new features and contributors
nesquena authored
258 $ terminitor start
259
260 This would clone the project repo, and then install all dependencies and then launch the ideal development environment for the project. Clearly
261 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
262 different configurations in the future.
263
1b4b70a @nesquena Added the delete command to the readme
nesquena authored
264 In addition, you are in the project folder and you wish to remove the Termfile, you can invoke the command:
265
266 $ terminitor delete
267
268 This will clear the `Termfile` for the particular project.
269
737eca0 @achiu update README
authored
270 ### Capturing Terminal Settings with Terminitor ###
74c9fa2 @achiu update README
authored
271 _Currently Mac OSX Terminal only_
737eca0 @achiu update README
authored
272 Terminitor has the ability to also capture your terminal setup and settings simply with:
273
274 $ terminitor edit my_project --capture
275
276 this will open up a new terminitor project with the captured settings for you to continuing modifying as you see fit.
277
5659f04 @achiu update README
authored
278
279 ### Fetching Github Projects with Terminitor ###
280
74c9fa2 @achiu update README
authored
281 Terminitor can also fetch code repositories off Github. This will have terminitor clone the repo into the current directory:
5659f04 @achiu update README
authored
282
283 $ terminitor fetch achiu terminitor
74c9fa2 @achiu update README
authored
284
5659f04 @achiu update README
authored
285 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:
286
287 $ terminitor fetch achiu terminitor --setup=false
288
289 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!
290
291
292 Cores
293 -----
294
295 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:
296
297 * MacCore - Mac OS X Terminal
298 * KonsoleCore - KDE Konsole
299
300 Feel free to contribute more cores so that Terminitor can support your terminal of choice :)
301
302
46dcb5d @nesquena Added initial readme
nesquena authored
303 Limitations
304 -----------
305
5659f04 @achiu update README
authored
306 #### MacCore ####
46dcb5d @nesquena Added initial readme
nesquena authored
307
5659f04 @achiu update README
authored
308 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
309 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
310
5659f04 @achiu update README
authored
311 #### Fetching ####
312
8dac74b @achiu update README
authored
313 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
314
737eca0 @achiu update README
authored
315
316 #### Settings and Captures ####
317
318 This feature is currently only available in Mac OS X at the moment.
319
320
00e3ac8 @nesquena Updated readme with authors.
nesquena authored
321 Authors
322 -------
323
34abdde @nesquena Updated README with new features and contributors
nesquena authored
324 The core code was adapted before by Nathan Esquenazi and Thomas Shafer.
325 In September 2010, Arthur Chiu and Nathan Esquenazi gemified and released this to gemcutter.
326
327 Contributors
328 -------------
329
330 Thanks to the following people for their contributions so far:
331
23ba406 @achiu fix/update README
authored
332 * Pat George ([pcg79](https://github.com/pcg79)) for contributing a patch for when a project is not found.
333 * Flavio Castelli ([flavio](https://github.com/flavio)) for contributing Konsole(KDE) core.
334 * Alexey Kuleshov ([kulesa](https://github.com/kulesa)) for contributing the terminal settings and terminal settings capture functionality
335 * Arthur Gunn ([gunn](https://github.com/gunn)) for contributing a path to support tab syntax and load path.
336 * Elliot Winkler ([mcmire](https://github.com/mcmire)) for adding 1.8.6 compatiblity and ensuring tabs open in order.
1554d62 @achiu update README
authored
337
46dcb5d @nesquena Added initial readme
nesquena authored
338 Acknowledgements
339 -----------------
340
b8c9ecf @nesquena Added the note about Jeff Emminger being the original developer of th…
nesquena authored
341
342
343 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).
344
345 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.
346 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
347
348 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
349 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
350 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.