doc/ranger.1


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224

.TH RANGER 1 ranger-1.3.0
.SH NAME
ranger - visual file manager
.\"-----------------------------------------
.SH SYNOPSIS
.B ranger
.R [OPTIONS] [FILE]
.\"-----------------------------------------
.SH DESCRIPTION
Ranger is a file manager with an ncurses frontend written in Python.
.P
It is designed to give you a broader overview of the file system by displaying
previews and backviews, dividing the screen into several columns.
The keybindings are similar to those of other console programs like
.BR vim ", " mutt " or " ncmpcpp
so the usage will be intuitive and efficient.
.\"-----------------------------------------
.SH OPTIONS
.TP
--version
Print the version and exit.
.TP
-h, --help
Print a list of options and exit.
.TP
-d, --debug
Activate the debug mode:  Whenever an error occurs, ranger will exit and
print a full backtrace.  The default behaviour is to merely print the
name of the exception in the statusbar/log and to try to keep running.
.TP
-c, --clean
Activate the clean mode:  Ranger will not access or create any configuration
files nor will it leave any traces on your system.  This is useful when
your configuration is broken, when you want to avoid clutter, etc.
.TP
--copy-config
Create copies of the default configuration files in your local configuration
directory.  Existing ones will not be overwritten.
.TP
--fail-unless-cd
Return the exit code 1 if ranger is used to run a file, for example with
`ranger --fail-unless-cd filename`.  This can be useful for scripts.
.TP
-r \fIdir\fR, --confdir=\fIdir\fR
Define a different configuration directory.  The default is
$XDG_CONFIG_HOME/ranger (which defaults to ~/.config/ranger)
.TP
-m \fIn\fR, --mode=\fIn\fR
When a filename is supplied, make it run in mode \fIn\fR. Check the
documentation for more information on modes.
.TP
-f \fIflags\fR, --flags=\fIflags\fR
When a filename is supplied, make it run with the flags \fIflags\fR. Check the
documentation for more information on flags.
.\"-----------------------------------------
.SH USAGE
.\"-----------------------------------------
.SS General Keybindings
Many keybindings take an additional numeric argument.  Type \fI5j\fR to move
down 5 lines, \fI10<Space>\fR to mark 10 files or \fI3?\fR to read the
third chapter of the documentation.
.TP
h, j, k, l
Move left, down, up, right
.TP
^D or J, ^U or K
Move a half page down, up
.TP
H, L
Move back and forward in the history
.TP
gg
Move to the top
.TP
G
Move to the bottom
.TP
^R
Reload everything
.TP
^L
Redraw the screen
.TP
S
Open a shell in the current directory
.TP
yy
Yank the selection.  (mark the files as copied)
.TP
dd
Cut the selection
.TP
pp
Paste the copied/cut files.  By default, this will not overwrite existing
files.  To overwrite them, use \fBpo\fR.
.TP
m\fIX\fR
Create a bookmark with the name \fIX\fR
.TP
`\fIX\fR
Move to the bookmark with the name \fIX\fR
.TP
n, N
Find the next file, the previous file.  You can define what to look for
by typing c\fIX\fR.  If nothing is specified, pressing n will get you to
the newest file in the directory.
.TP
o\fIX\fR
Change the sort method (like in mutt)
.TP
z\fIX\fR
Change settings
.TP
f
Quickly navigate by entering a part of the filename
.TP
Space
Mark a file
.TP
v, V
Toggle the mark-status of all files, unmark all files
.TP
/
Open the search console
.TP
:
Open the command console
.TP
?
Opens the help screen with more keybindings and documentation
.\"-----------------------------------------
.SS Keybindings for using Tabs
Tabs are used to work in different directories in the same Ranger instance.
.TP
g\fIN\fR
Open a tab. N has to be a number from 0 to 9. If the tab doesn't exist yet,
it will be created.
.TP
gn, ^N
Create a new tab.
.TP
gt, gT
Go to the next or previous tab.  You can also use TAB and SHIFT+TAB.
.TP
gc, ^W
Close the current tab.  The last tab cannot be closed.
.P
.\"-----------------------------------------
.SS Mouse Usage
.TP
Left Mouse Button
Click on something and you'll move there.
To run a file, "enter" it, like a directory, by clicking on the preview.
.TP
Right Mouse Button
Enter a directory
.TP
Scroll Wheel
Scroll
.\"-----------------------------------------
.SS Commands
.TP
:delete
Destroy all files in the selection with a roundhouse kick.  Ranger will
ask for a confirmation if you attempt to delete multiple (marked) files or
non-empty directories.
.TP
:rename \fInewname\fR
Rename the current file.  Also try the keybinding A for appending something
to a file name.
.TP
:quit
Quit ranger.  The current directory will be bookmarked as ' so you can
re-enter it by typing `` or '' the next time you start ranger.
.\"-----------------------------------------
.SH TIPS
.SS
Change the directory after exit
A script like this in your bashrc would make you change the directory
of your parent shell after exiting ranger:
.nf

ranger() {
    command ranger --fail-unless-cd $@ &&
    cd "$(grep \\^\\' ~/.config/ranger/bookmarks | cut -b3-)"
}
.\"-----------------------------------------
.SH CONFIGURATION
The files in
.B ranger/defaults/
can be copied into your configuration directory (by default, this is
~/.config/ranger) and customized according to your wishes.
Most files don't have to be copied completely though: Just define those
settings you want to add or change and they will override the defauls.
Colorschemes can be placed in ~/.config/ranger/colorschemes.
.P
All configuration is done in Python.
Each configuration file should contain sufficient documentation.
.\"-----------------------------------------
.SH COPYRIGHT
Copyright \(co
2009, 2010
Roman Zimbelmann
.P
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.

There is NO warranty;
not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.\"-----------------------------------------
.SH SEE ALSO
The project page:
.RB < http://savannah.nongnu.org/projects/ranger >
.P
The mailing list:
.RB < http://savannah.nongnu.org/mail/?group=ranger >
.\"-----------------------------------------
.SH BUGS
Please report them here and include as much relevant information
as possible:
.P
.RB < http://savannah.nongnu.org/bugs/?group=ranger >
//: The goal of this skeleton is to make programs more easy to understand and
//: more malleable, easy to rewrite in radical ways without accidentally
//: breaking some corner case. Tests further both goals. They help
//: understandability by letting one make small changes and get feedback. What
//: if I wrote this line like so? What if I removed this function call, is it
//: really necessary? Just try it, see if the tests pass. Want to explore
//: rewriting this bit in this way? Tests put many refactorings on a firmer
//: footing.
//:
//: But the usual way we write tests seems incomplete. Refactorings tend to
//: work in the small, but don't help with changes to function boundaries. If
//: you want to extract a new function you have to manually test-drive it to
//: create tests for it. If you want to inline a function its tests are no
//: longer valid. In both cases you end up having to reorganize code as well as
//: tests, an error-prone activity.
//:
//: This file tries to fix this problem by supporting domain-driven testing
//: We try to focus on the domain of inputs the program should work on. All
//: tests invoke the program in a single way: by calling run() with different
//: inputs. The program operates on the input and logs _facts_ it deduces to a
//: trace:
//:   trace("label") << "fact 1: " << val;
//:
//: The tests check for facts:
//:   :(scenario foo)
//:   34  # call run() with this input
//:   +label: fact 1: 34  # trace should have logged this at the end
//:   -label: fact 1: 35  # trace should never contain such a line
//:
//: Since we never call anything but the run() function directly, we never have
//: to rewrite the tests when we reorganize the internals of the program. We
//: just have to make sure our rewrite deduces the same facts about the domain,
//: and that's something we're going to have to do anyway.
//:
//: To avoid the combinatorial explosion of integration tests, we organize the
//: program into different layers, and each fact is logged to the trace with a
//: specific label. Individual tests can focus on specific labels. In essence,
//: validating the facts logged with a specific label is identical to calling
//: some internal subsystem.
//:
//: Traces interact salubriously with layers. Thanks to our ordering
//: directives, each layer can contain its own tests. They may rely on other
//: layers, but when a test fails its usually due to breakage in the same
//: layer. When multiple tests fail, it's usually useful to debug the very
//: first test to fail. This is in contrast with the traditional approach,
//: where changes can cause breakages in faraway subsystems, and picking the
//: right test to debug can be an important skill to pick up.
//:
//: To build robust tests, trace facts about your domain rather than details of
//: how you computed them.
//:
//: More details: http://akkartik.name/blog/tracing-tests
//:
//: ---
//:
//: Between layers and domain-driven testing, programming starts to look like a
//: fundamentally different activity. Instead of a) superficial, b) local rules
//: on c) code [like http://blog.bbv.ch/2013/06/05/clean-code-cheat-sheet],
//: we allow programmers to engage with the a) deep, b) global structure of the
//: c) domain. If you can systematically track discontinuities in the domain
//: you don't care if the code used gotos as long as it passed the tests. If
//: tests become more robust to run it becomes easier to try out radically
//: different implementations for the same program. If code is super-easy to
//: rewrite, it becomes less important what indentation style it uses, or that
//: the objects are appropriately encapsulated, or that the functions are
//: referentially transparent.
//:
//: Instead of plumbing, programming becomes building and gradually refining a
//: map of the environment the program must operate under. Whether a program is
//: 'correct' at a given point in time is a red herring; what matters is
//: avoiding regression by monotonically nailing down the more 'eventful' parts
//: of the terrain. It helps readers new and old and rewards curiosity to
//: organize large programs in self-similar hiearchies of example scenarios
//: colocated with the code that makes them work.
//:
//:   "Programming properly should be regarded as an activity by which
//:   programmers form a mental model, rather than as production of a program."
//:   -- Peter Naur (http://alistair.cockburn.us/ASD+book+extract%3A+%22Naur,+Ehn,+Musashi%22)

:(before "int main")
// End Tracing  // hack to ensure most code in this layer comes before anything else

:(before "End Tracing")
bool Hide_warnings = false;
:(before "End Setup")
//? cerr << "AAA setup\n"; //? 2
Hide_warnings = false;

:(before "End Types")
struct trace_line {
  int depth;  // optional field just to help browse traces later
  string label;
  string contents;
  trace_line(string l, string c) :depth(0), label(l), contents(c) {}
  trace_line(int d, string l, string c) :depth(d), label(l), contents(c) {}
};

:(before "End Tracing")
struct trace_stream {
  vector<trace_line> past_lines;
  // accumulator for current line
  ostringstream* curr_stream;
  string curr_layer;
  int curr_depth;
  string dump_layer;
  set<string> collect_layers;  // if not empty, ignore all absent layers
  ofstream null_stream;  // never opens a file, so writes silently fail
  trace_stream() :curr_stream(NULL), curr_depth(0) {}
  ~trace_stream() { if (curr_stream) delete curr_stream; }

  ostream& stream(string layer) {
    return stream(0, layer);
  }

  ostream& stream(int depth, string layer) {
    if (!is_collecting(layer)) return null_stream;
    curr_stream = new ostringstream;
    curr_layer = layer;
    curr_depth = depth;
    return *curr_stream;
  }

  bool is_collecting(const string& layer) {
    return collect_layers.empty() || collect_layers.find(layer) != collect_layers.end();
  }

  bool is_narrowly_collecting(const string& layer) {
    return collect_layers.find(layer) != collect_layers.end();
  }

  // be sure to call this before messing with curr_stream or curr_layer
  void newline() {
    if (!curr_stream) return;
    string curr_contents = curr_stream->str();
    if (curr_contents.empty()) return;
    past_lines.push_back(trace_line(curr_depth, trim(curr_layer), curr_contents));  // preserve indent in contents
    if (curr_layer == dump_layer || curr_layer == "dump" || dump_layer == "all" ||
        (!Hide_warnings && curr_layer == "warn"))
//?     if (dump_layer == "all" && (Current_routine->id == 3 || curr_layer == "schedule")) //? 1
      cerr << curr_layer << ": " << curr_contents << '\n';
    delete curr_stream;
    curr_stream = NULL;
    curr_layer.clear();
    curr_depth = 0;
  }

  // Useful for debugging.
  string readable_contents(string layer) {  // missing layer = everything
    ostringstream output;
    layer = trim(layer);
    for (vector<trace_line>::iterator p = past_lines.begin(); p != past_lines.end(); ++p)
      if (layer.empty() || layer == p->label) {
        if (p->depth)
          output << std::setw(4) << p->depth << ' ';
        output << p->label << ": " << p->contents << '\n';
      }
    return output.str();
  }
};


trace_stream* Trace_stream = NULL;

// Top-level helper. IMPORTANT: can't nest.
#define trace(...)  !Trace_stream ? cerr /*print nothing*/ : Trace_stream->stream(__VA_ARGS__)
// Warnings should go straight to cerr by default since calls to trace() have
// some unfriendly constraints (they delay printing, they can't nest)
#define raise  ((!Trace_stream || !Hide_warnings) ? (tb_shutdown(),cerr) /*do print*/ : Trace_stream->stream("warn"))

:(before "End Types")
struct end {};
:(before "End Tracing")
ostream& operator<<(ostream& os, unused end) {
  if (Trace_stream) Trace_stream->newline();
  return os;
}

#define CLEAR_TRACE  delete Trace_stream, Trace_stream = new trace_stream;

#define DUMP(layer)  if (Trace_stream) cerr << Trace_stream->readable_contents(layer);

// All scenarios save their traces in the repo, just like code. This gives
// future readers more meat when they try to make sense of a new project.
static string Trace_dir = ".traces/";
string Trace_file;

// Trace_stream is a resource, lease_tracer uses RAII to manage it.
struct lease_tracer {
  lease_tracer() { Trace_stream = new trace_stream; }
  ~lease_tracer() {
//?     cerr << "write to file? " << Trace_file << "$\n"; //? 2
    if (!Trace_file.empty()) {
//?       cerr << "writing\n"; //? 2
      ofstream fout((Trace_dir+Trace_file).c_str());
      fout << Trace_stream->readable_contents("");
      fout.close();
    }
    delete Trace_stream, Trace_stream = NULL, Trace_file = "";
  }
};

#define START_TRACING_UNTIL_END_OF_SCOPE  lease_tracer leased_tracer;
:(before "End Test Setup")
START_TRACING_UNTIL_END_OF_SCOPE
//? Trace_stream->dump_layer = "all"; //? 1

#define CHECK_TRACE_CONTENTS(...)  check_trace_contents(__FUNCTION__, __FILE__, __LINE__, __VA_ARGS__)

:(before "End Tracing")
bool check_trace_contents(string FUNCTION, string FILE, int LINE, string expected) {  // missing layer == anywhere
  vector<string> expected_lines = split(expected, "");
  long long int curr_expected_line = 0;
  while (curr_expected_line < SIZE(expected_lines) && expected_lines.at(curr_expected_line).empty())
    ++curr_expected_line;
  if (curr_expected_line == SIZE(expected_lines)) return true;
  string layer, contents;
  split_layer_contents(expected_lines.at(curr_expected_line), &layer, &contents);
  for (vector<trace_line>::iterator p = Trace_stream->past_lines.begin(); p != Trace_stream->past_lines.end(); ++p) {
//?     cerr << "AAA " << layer << ' ' << p->label << '\n'; //? 1
    if (layer != p->label)
      continue;

//?     cerr << "BBB ^" << contents << "$ ^" << p->contents << "$\n"; //? 1
    if (contents != trim(p->contents))
      continue;

//?     cerr << "CCC\n"; //? 1
    ++curr_expected_line;
    while (curr_expected_line < SIZE(expected_lines) && expected_lines.at(curr_expected_line).empty())
      ++curr_expected_line;
    if (curr_expected_line == SIZE(expected_lines)) return true;
    split_layer_contents(expected_lines.at(curr_expected_line), &layer, &contents);
  }

  ++Num_failures;
  cerr << "\nF - " << FUNCTION << "(" << FILE << ":" << LINE << "): missing [" << contents << "] in trace:\n";
  DUMP(layer);
//?   exit(0); //? 1
  Passed = false;
  return false;
}

void split_layer_contents(const string& s, string* layer, string* contents) {
  static const string delim(": ");
  size_t pos = s.find(delim);
  if (pos == string::npos) {
    *layer = "";
    *contents = trim(s);
  }
  else {
    *layer = trim(s.substr(0, pos));
    *contents = trim(s.substr(pos+SIZE(delim)));
  }
}


int trace_count(string layer) {
  return trace_count(layer, "");
}

int trace_count(string layer, string line) {
  long result = 0;
  for (vector<trace_line>::iterator p = Trace_stream->past_lines.begin(); p != Trace_stream->past_lines.end(); ++p) {
    if (layer == p->label) {
//?       cerr << "a: " << line << "$\n"; //? 1
//?       cerr << "b: " << trim(p->contents) << "$\n"; //? 1
      if (line == "" || line == trim(p->contents))
        ++result;
    }
  }
  return result;
}

#define CHECK_TRACE_WARNS()  CHECK(trace_count("warn") > 0)
#define CHECK_TRACE_DOESNT_WARN() \
  if (trace_count("warn") > 0) { \
    ++Num_failures; \
    cerr << "\nF - " << __FUNCTION__ << "(" << __FILE__ << ":" << __LINE__ << "): unexpected warnings\n"; \
    DUMP("warn"); \
    Passed = false; \
    return; \
  }

bool trace_doesnt_contain(string layer, string line) {
  return trace_count(layer, line) == 0;
}

bool trace_doesnt_contain(string expected) {
  vector<string> tmp = split(expected, ": ");
  return trace_doesnt_contain(tmp.at(0), tmp.at(1));
}

#define CHECK_TRACE_DOESNT_CONTAIN(...)  CHECK(trace_doesnt_contain(__VA_ARGS__))


vector<string> split(string s, string delim) {
  vector<string> result;
  size_t begin=0, end=s.find(delim);
  while (true) {
    if (end == string::npos) {
      result.push_back(string(s, begin, string::npos));
      break;
    }
    result.push_back(string(s, begin, end-begin));
    begin = SIZE(end+delim);
    end = s.find(delim, begin);
  }
  return result;
}

string trim(const string& s) {
  string::const_iterator first = s.begin();
  while (first != s.end() && isspace(*first))
    ++first;
  if (first == s.end()) return "";

  string::const_iterator last = --s.end();
  while (last != s.begin() && isspace(*last))
    --last;
  ++last;
  return string(first, last);
}

:(before "End Includes")
#include<vector>
using std::vector;
#include<list>
using std::list;
#include<map>
using std::map;
#include<set>
using std::set;
#include<algorithm>

#include<iostream>
using std::istream;
using std::ostream;
using std::cin;
using std::cout;
using std::cerr;
#include<iomanip>

#include<sstream>
using std::istringstream;
using std::ostringstream;

#include<fstream>
using std::ifstream;
using std::ofstream;

#include"termbox/termbox.h"

#define unused  __attribute__((unused))

:(before "End Globals")
//: In future layers we'll use the depth field as follows:
//:
//: Mu 'applications' will be able to use depths 1-99 as they like.
//: Depth 100 will be for scheduling (more on that later).
const int Scheduling_depth = 100;
//: Primitive statements will occupy 101-9998
const int Initial_callstack_depth = 101;
const int Max_callstack_depth = 9998;
//: (ignore this until the call layer)
:(before "End Globals")
int Callstack_depth = 0;
:(before "End Setup")
Callstack_depth = 0;
//: Finally, details of primitive mu statements will occupy depth 9999 (more on that later as well)
:(before "End Globals")
const int Primitive_recipe_depth = 9999;
//:
//: This framework should help us hide some details at each level, mixing
//: static ideas like layers with the dynamic notion of call-stack depth.