Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/roman/navorski.el

Define profiles for local/remote terminals and services on emacs
https://github.com/roman/navorski.el

Last synced: 3 months ago
JSON representation

Define profiles for local/remote terminals and services on emacs

Host: GitHub
URL: https://github.com/roman/navorski.el
Owner: roman
License: other
Created: 2014-04-25T19:19:52.000Z (over 10 years ago)
Default Branch: master
Last Pushed: 2023-04-16T22:51:57.000Z (over 1 year ago)
Last Synced: 2024-04-14T13:11:14.776Z (7 months ago)
Language: Emacs Lisp
Homepage:
Size: 310 KB
Stars: 19
Watchers: 5
Forks: 1
Open Issues: 2
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# navorski.el

navorski.el is an emacs extension that facilitates the management of
terminals (local or remote).

## Emacs version

This extension has been tested with emacs 24.3.1 on Mac OS X Lion/Mavericks
and Gentoo.

## Dependencies

This extension will require:

* [s.el](https://github.com/magnars/s.el)
* [dash.el](https://github.com/magnars/dash.el)
* [multi-term](https://github.com/emacsmirror/multi-term)

## Installation

### Melpa

You can install this extensions through
[MELPA](https://github.com/milkypostman/melpa)

### Cask

If you want to use the _bleeding edge_ version of navorski in your
emacs setup add this to your [Cask](https://github.com/cask/cask) file
(note you'll need cask >= 0.7.1)

```elisp
(depends-on "navorski"
:git "https://github.com/roman/navorski.el.git")
```

You can also specify the `depends-on` without the git option, and it
should download the last stable version.

## Getting Started

navorski.el provides all the functions you will need to interact with
a terminal through the `nav/defterminal` macro.

When using `defterminal`, a variable with the name used on the first
parameter is created, you can use this variable to call different
functions. Let's suppose you are working on a project named foobar
and you want to have a dedicated ipython terminal for it:

```elisp
(nav/defterminal foobar-ipython
:buffer-name "ipython-console"
:program-path "/usr/bin/ipython"
:cwd "/Users/johndoe/Projects/foobar")
```

Once this is declared, you can call `(nav/pop-to-buffer
foobar-ipython)` and a new buffer with the process specified in that
profile will be executed. This particular example creates a
rudimentary ipython inferior-mode. You can then create your own
keybindings or helper functions to interact with this process buffer.

## Example + explanations

```elisp
(require 'navorski)

(nav/defterminal production-console
:buffer-name "production-console"
:interactive t ;; (1)
:remote-host "user@production" ;; (2)
:screen-session-name "production_console" ;; (3)
:init-script ("cd project-path" "bundle exec rails c") ;; (4)
)

;; M-x: nav/production-console-pop-to-buffer
;; will open a new buffer to a production rails console

(nav/defterminal foobar-ipython
:buffer-name "ipython-console"
:cwd "/Users/johndoe/Projects/foobar" ;; (5)
:program-path "/usr/bin/ipython" ;; (6)
)

```

### (1) Creating interactive profile functions on the fly

If you don't want to get your hands dirty doing custom functions
that used the terminal profile, you can pass the `:interactive`
flag to the `defterminal` call. This will generate the following
functions:

* `nav/-pop-to-buffer`
* `nav/-kill-buffer`
* `nav/-send-string`
* `nav/-send-region`

Creating terminal profiles is really easy, for this reason every
terminal profile should have one purpose, if you need to have a
terminal to do something specific, just create a new profile
and call the generated `pop-to-buffer` function. An example of this:

### (2) Remote Terminals

Your terminals don't need to be only local, you can specify a
`:remote-host` option to create a remote terminal via SSH.

Another way to create a remote-terminal without a `defterminal`
profile is via the function `nav/remote-term`. Navorski offers by
default a tramp setup on the remote machine, _this feature will only
work if the SSH authentication happens via public/private keys_.

### (3) Persistent Terminals

Another nice feature is the ability to automatically create a GNU
Screen session on an specified terminal, this is really useful when
working with remote terminals. Just need to provide the
`:screen-session-name` to a `defterminal` profile.

Another way to create a persistent-terminal without a `defterminal`
profile is via the function `nav/persistent-term`. It's important to
note that the `:program-args` parameter will not work when using
persistent terminals, this is a limitation of the GNU Screen
program. You can however trick this by creating a custom bash script
with all the arguments you need and call that script from navorski
instead.

### (4) Executing bash when terminal is initialized

Sometimes in order to get a terminal to a desired state you want to
execute a group of commands after it is created. The `:init-script`
option allows you to pass a list of strings that represent bash
commands.

### (5) Change working directory of a program execution

With the `:cwd` option, you may specify either:

* a string that will be the `default-directory` when a navorski
command is called

* a function that recevies the `default-directory` and returns a new
value for it when a navorski command is called (this is
particularly useful in combiation of `locate-dominating-file`)

This option won't work correctly on remote terminals, you may do a
`cd` command on the :init-script option instead.

### (6) Create buffer processes that are not just terminals

The `:program-path` allows you to specify a different program for the
created terminal buffer. This particular example creates an ipython
inferior mode.

## Why the name navorski?

Viktor Navorski is a fictional character from the movie [The
Terminal](http://en.wikipedia.org/wiki/The_Terminal), that _lived_ in
a terminal. Got the pun right?

## Development

Pull requests are very welcome! Please try to follow these simple rules if applicable:

* Please create a topic branch for every separate change you make.

* Update the README file.

* Please **do not change** the version number.

#### Open Commit Bit

navorski.el has an open commit bit policy: Anyone with an accepted
pull request gets added as a repository collaborator. Please try to
follow these simple rules:

* Commit directly onto the master branch only for typos, improvements
to the readme and documentation.

* Create a feature branch and open a pull-request early for any new
features to get feedback.

* Make sure you adhere to the general pull request rules above.

## License

```
navorski.el - Making you live in the terminal

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see .
```