1=======================
2lfm - Last File Manager
3=======================
4
5:Author: Iñigo Serna, inigoserna AT gmail DOT com
6
7:Version: 3.1, June 25th. 2017
8
9:Home page: https://inigo.katxi.org/devel/lfm/
10
11:License: | Copyright © 2001-17, Iñigo Serna
12 | This software has been realised under the `GPL License
13 <http://www.gnu.org/licenses/licenses.html#GPL>`_ version 3
14 or later, read the `<COPYING>`_ file that comes with this package
15 for more information.
16 | There is NO WARRANTY.
17
18:Last update: |date|
19
20.. meta::
21 :description: Last File Manager is a powerful file manager for the UNIX console
22 :keywords: lfm, file manager, python, ncurses
23
24.. contents:: Table of Contents
25
26
27Introduction
28============
29**Last File Manager** is a powerful file manager for the UNIX console.
30It has a curses interface and it's written in Python v3.4+.
31
32Some of the features you can find in *lfm*:
33
34- console-based file manager for UNIX platforms
35- 1-pane or 2-pane view
36- tabs
37- files filters
38- bookmarks
39- history
40- VFS for compressed files
41- tree view
42- dialogs with entry completion
43- PowerCLI, a command line interface with advanced features
44- fast access to the shell
45- direct integration of find/grep, df and other tools
46- color files by extension [Andrey Skvortsov]
47- fully customizable themes (colors)
48- fully customizable key bindings
49- support for filenames with wide chars, f.e. East Asian
50- ...and many others
51
52Some screenshots:
53
54.. table:: **Last File Manager**
55
56 =============================== ===============================
57 .. image:: lfm-1.png .. image:: lfm-2.png
58 *Tabs and compressed file VFS* *File completion*
59 ------------------------------- -------------------------------
60 .. image:: lfm-3.png .. image:: lfm-4.png
61 *Tree view* *Edit filter*
62 ------------------------------- -------------------------------
63 .. image:: lfm-5.png .. image:: lfm-6.png
64 *PowerCLI* *Find & grep*
65 =============================== ===============================
66
67When *lfm* starts the first time, it tries to discover the location of
68some programs in your system to configure itself automatically, but you
69should take a look to the configuration (`General Menu [F9] -> Edit
70Configuration [c]`) in case you want to change something.
71
72Consult `Customization`_ section for in-depth knowledgement
73about all the settings and their meaning.
74
75Finally, take a look at `<TODO>`_ file to check known bugs and
76*not-implemented-yet*\™ features.
77
78**Last File Manager** development can be followed in the
79`BitBucket mercurial repository <https://bitbucket.org/inigoserna/lfm3>`_.
80
81
82Download and installation
83=========================
84
85Requirements
86------------
87*lfm* is written in `Python <http://www.python.org>`_ language and
88has a text-based ncurses interface.
89
90It should run with Python v3.4 or higher and doesn't need additional
91modules or any other dependencies, only those provided by the python
92standard library.
93
94For systems with Python v2.x only, use the old version *lfm v2.3*.
95
96All modern UNIX flavours (Linux, \*BSD, Solaris, etc) should run it without
97problems. But note I mostly tested the new 3.x series on Linux.
98If they appear any issues please notify me.
99
100Installation
101------------
102.. sidebar:: **Files:** all releases
103 :class: warning
104
105 .. list-table::
106 :widths: 10 15 10
107 :header-rows: 1
108
109 * - Version
110 - File
111 - Date
112 * - 3.1
113 - `<lfm-3.1.tar.gz>`_
114 - 2017/06/25
115 * - 3.0
116 - `<lfm-3.0.tar.gz>`_
117 - 2015/10/23
118 * - 2.3
119 - `<lfm-2.3.tar.gz>`_
120 - 2011/05/21
121 * - 2.2
122 - `<lfm-2.2.tar.gz>`_
123 - 2010/05/22
124 * - 2.1
125 - `<lfm-2.1.tar.gz>`_
126 - 2008/12/21
127 * - 2.0
128 - `<lfm-2.0.tar.gz>`_
129 - 2007/09/03
130 * - 1.0
131 - Never released
132 - ~2006
133 * - 0.91
134 - `<lfm-0.91.tar.gz>`_
135 - 2004/07/03
136 * - 0.9
137 - `<lfm-0.9.tar.gz>`_
138 - 2002/09/05
139 * - 0.8
140 - `<lfm-0.8.tar.gz>`_
141 - 2002/03/04
142 * - 0.7
143 - `<lfm-0.7.tar.gz>`_
144 - 2001/11/30
145 * - 0.5
146 - `<lfm-0.5.tar.gz>`_
147 - 2001/08/07
148 * - 0.4
149 - `<lfm-0.4.tar.gz>`_
150 - 2001/07/19
151
152 Read about `<NEWS>`_.
153
154*lfm* is very easy to install, select one of these options.
155
156* First, check if your OS include *lfm* in their repositories. Type as root:
157
158 ``# dnf install lfm # fedora/redhat/centos/…``
159
160 ``# pacman -S lfm # archlinux``
161
162 ``# apt-get install lfm # debian/ubuntu/mint/…``
163
164 **NOTE 1**: be sure to install *lfm* version 3 or higher, not old version 2.3!
165
166 **NOTE 2**: `lfm` is not usually included in main distributions repositories.
167
168* Using pip:
169
170 ``$ pip install lfm``
171
172* To install from sources:
173
174 1. Download `sources <lfm-3.1.tar.gz>`_
175 2. Uncompress file:
176 ``$ tar xvfz lfm-3.1.tar.gz``
177 3. Enter the directory and build:
178 ``$ python setup.py build``
179 4. Install, as root:
180 ``# python setup.py install``
181
182 **WARNING**: Remember *lfm 3.x* requires Python 3.4+. If you have
183 installed both python 2.x and 3.x versions on your system, change
184 ``python`` with ``python3`` and ``pip`` with ``pip3`` above.
185
186Now to run it:
187 ``$ lfm``
188
189and to change default settings:
190 `General Menu [F9] -> Edit Configuration [c]`
191
192To let *lfm* to change to panel's current directory after quiting with
193``q`` or ``F10`` keys, you must add next code to ``/etc/bashrc``
194or to your ``~/.bashrc``::
195
196 lfm()
197 {
198 /usr/bin/lfm "$@" # type here full path to lfm script
199 LFMPATHFILE=/tmp/lfm-$$.path
200 cd "`cat $LFMPATHFILE`" && rm -f $LFMPATHFILE
201 }
202
203If you don't use bash or csh shell, above lines could differ.
204
205Upgrading from 2.x to 3.x
206-------------------------
207Some notes about the upgrade process from *lfm* version 2.x to 3.x:
208
209- *lfm* 3.0 has been almost completely rewritten from scratch,
210 and it hasn't been tested as much as lfm v2.x series on non-linux OS.
211
212- *lfm* 3.x requires python 3.4+, it will not work with python 2.x.
213
214- Configuration has moved from the file ``~/.lfmrc`` to the directory
215 ``~/.config/lfm/``. You can delete ``~/.lfmrc`` from your system as
216 it is not used anymore. See section `Customization`_ later.
217
218- Also, note that some key bindings and PowerCLI variables have
219 changed since previous versions. Read documentation carefully.
220
221- *pyview* —the file viewer— has been removed from *lfm* package, as
222 well as old references to it in configuration, code and documentation.
223 Thus, default viewer has been changed to `less`. See `FAQ`_ entry.
224
225More information in the `<NEWS>`_ file.
226
227
228Keys shortcuts
229==============
230In this section you can find the complete list of key shortcuts used in *lfm*.
231Read `Key bindings`_ section if you want to customize them.
232
233Global
234------
235+ **Movement**
236 - up, k
237 - down, j
238 - page_up, backspace, Ctrl-p
239 - page_down, space, Ctrl-n
240 - Ctrl-up: move cursor up 10
241 - Ctrl-down: move cursor down 10
242 - home, Ctrl-a: move cursor to first file
243 - end, Ctrl-e: move cursor to last file
244 - Ctrl-s: go to file whose name contains…
245 - Alt-s: go to file whose first letter is…
246
247+ **Change directory**
248 - left: parent dir
249 - right, enter: enter dir / vfs
250 - g: go to directory…
251 - b: go to bookmark… [0-9a-z]
252 - B: set bookmark… [0-9a-z]
253 - Ctrl-d: select bookmark from menu…
254 - Ctrl-y: select directory from navigation history…
255
256+ **Panes**
257 - tab: other pane
258 - =: show same directory in both panes
259 - , Ctrl-u: change panes position (left<->right)
260 - .: toggle display 1 or 2 panes
261 - Ctrl-h: toggle show/hide dot-files
262 - Ctrl-f: edit filter for active tab…
263 - s: sort files by…
264 - #: show selected/all directories size
265 - Ctrl-r: refresh contents
266 - Alt-r: redraw screen
267
268+ **Tabs**
269 - :: new tab
270 - !: close tab
271 - <: go to left tab
272 - >: go to right tab
273
274+ **Selections**
275 - insert: select item and move cursor to next file
276 - +: select group…
277 - -: deselect group…
278 - \*: invert selection
279
280+ **Files / Directories operations**
281 - F2: rename file/dir…
282 - F3: view file
283 - F4: edit file
284 - F5: copy file/dir/selection…
285 - F6: move file/dir/selection…
286 - F7: make directory…
287 - F8: delete file/dir/selection
288 - enter: execute file, enter dir / vfs or view 'specially' depending on the extension of the regular file. It is executed in a thread that can be stopped and captures output
289 - @: exec on file… (output is not captured)
290 - t: touch file…
291 - l: create link…
292 - L: edit link…
293 - i: show file info
294
295+ **Other**
296 - /: find/grep files…
297 - Ctrl-t: tree
298 - Ctrl-o: open shell. Type 'exit' or press Ctrl-d to return to lfm
299 - Ctrl-x: toggle show/hide PowerCLI
300 - F12: file menu
301 - @: exec on file(s) (output is not captured)
302 - i: show file info
303 - p: change file(s) permissions…
304 - o: change file(s) owner and/or group…
305 - a: backup file(s)…
306 - d: diff file with backup
307 - z: Compress/uncompress file(s)…
308 - g: gzip/gunzip
309 - b: bzip2/bunzip2
310 - x: xz/unxz
311 - l: lzip/lunzip
312 - 4: lz4/unlz4
313 - x: uncompress .tar.gz, .tar.bz2, .tar.xz, .tar.lz, .tar.lz4, .tar, .zip, .rar, .7z
314 - u: uncompress .tar.gz, etc in other panel
315 - c: compress directory to format…
316 - g: .tar.gz
317 - b: .tar.bz2
318 - x: .tar.xz
319 - l: .tar.lz
320 - 4: .tar.lz4
321 - t: .tar
322 - z: .zip
323 - r: .rar
324 - 7: .7z
325 - F9: general menu
326 - /: find/grep file…
327 - #: show directories size
328 - s: sort files by…
329 - t: tree
330 - f: show filesystems info
331 - o: open shell
332 - c: edit configuration
333 - k: edit key bindings file
334 - e: edit theme file
335 - h: delete history
336 - h: help…
337 - q, F10: exit and chdir to current path
338 - Ctrl-q: quit and don't change to current path
339
340Dialogs
341-------
342+ ***EntryLine* window and *PowerCLI***
343 - enter: return path or execute command in *PowerCLI*
344 - Ctrl-c, ESC: quit
345 - Ctrl-x: toggle show/hide in *PowerCLI*
346 - insert: toggle insert/overwrite
347 - special:
348 - up, down: history
349 - tab: change to next entry or button, or complete in *PowerCLI*
350 - Ctrl-t: complete…
351 - movement
352 - home, Ctrl-a: move to beginning of line
353 - end, Ctrl-e: move to end of line
354 - left, Ctrl-b: move cursor left
355 - right, Ctrl-f: move cursor right
356 - Ctrl-left, Ctrl-p: move cursor to previous word
357 - Ctrl-right, Ctrl-n: move cursor to next word
358 - deletion
359 - backspace: delete previous character
360 - del: delete character at cursor
361 - Ctrl-w: delete whole line
362 - Ctrl-h: delete from start to cursor position
363 - Ctrl-k: delete from cursor position to end of line
364 - Ctrl-q, Ctrl-backspace: delete until previous word
365 - Ctrl-r, Ctrl-del: delete until next word
366 - insertion
367 - Ctrl-z: restore original content (undo)
368 - Ctrl-v: insert filename at position
369 - Ctrl-s: insert path at position
370 - Ctrl-o: insert other pane tab path at position
371 - Ctrl-d, Ctrl-\: select bookmark at position…
372 - Ctrl-y: select path from navigation history at position…
373 - Ctrl-g: select historic path (not *PowerCLI*)…
374 - Ctrl-g: select historic or stored (from config) command (*PowerCLI*)…
375
376+ ***SelectItem* window**
377 - [letter]: go to entry whose first char is this
378 - up, k, K
379 - down, j, J
380 - page_up, backspace, Ctrl-b
381 - page_down, space, Ctrl-f
382 - home, Ctrl-a
383 - end, Ctrl-e
384 - Ctrl-l: go to entry in the middle of list
385 - Ctrl-s: go to entry starting by…
386 - enter: return entry
387 - Ctrl-c, q, Q, ESC: quit
388
389+ ***Permissions* and *Owner/Group* windows**
390 - tab, cursor: move
391 - in permissions: r, w, x, s, t to toggle read, write, exec, setuid or setgid, sticky bit
392 - in user, group: space or enter to select
393 - in recursive: space or enter to toggle
394 - in buttons: space or enter to accept that action
395 - everywhere: space or enter to accept, a to accept all, i to ignore and c, q, esc, Ctrl-c to cancel
396
397+ ***Tree* panel**
398 - down, j, K: down within current depth, without going out from directory
399 - up, k, K: up within current depth, without going out from directory
400 - page_up, backspace, Ctrl-b: same as up but page-size scroll
401 - page_down, space, Ctrl-f: same as down but page-size scroll
402 - home, Ctrl-a: first directory
403 - end, Ctrl-e: last directory
404 - left: go out from directory
405 - right: enter in directory
406 - enter: return changing to directory
407 - Ctrl-c, q, Q, F10, ESC: quit
408
409+ ***View* window**
410 - up, k, K
411 - down, j, J
412 - page_up, backspace, Ctrl-b
413 - page_down, space, Ctrl-f
414 - home, Ctrl-a: move cursor to first file
415 - end, Ctrl-e: move cursor to last file
416 - Ctrl-c, q, Q, F3, F10, ESC: quit
417
418
419Some features in detail
420=======================
421
422Running *lfm*
423-------------
424Type ``lfm --help`` for a complete list of options::
425
426 ~$ lfm --help
427 Usage: lfm [-h] [-d] [-w] [--restore-config] [--restore-keys]
428 [--restore-theme] [--delete-history]
429 [path1] [path2]
430
431 lfm v3.1 - (C) 2001-17, by Iñigo Serna <inigoserna@gmail.com>
432
433 positional arguments:
434 path1 Path to show in left pane (default: ".")
435 path2 Path to show in right pane (default: ".")
436
437 optional arguments:
438 -h, --help Show this help message and exit
439 -d, --debug Enable debug level in log file
440 -w, --use-wide-chars Enable support for wide chars
441 --restore-config Restore default configuration
442 --restore-keys Restore default key bindings
443 --restore-theme Restore default theme
444 --delete-history Delete history
445
446 'Last File Manager' is a powerful file manager for UNIX console.
447 It has a curses interface and it's written in Python version 3.4+.
448 Released under GNU Public License, read COPYING file for more details.
449
450As mentioned in the `Installation`_ section, quitting *lfm* with `q` or `F10`
451keys will leave you in the directory of active tab, if you want to go back
452to the directory you started *lfm* from, quit the program using `Ctrl-q`.
453
454When running *lfm* writes some events to the log file ``~/.config/lfm/lfm.log``.
455Passing ``-d`` or ``--debug`` to *lfm* increments the verbosity of the logs.
456
457Start the program with ``lfm -w`` or ``lfm --use-wide-chars`` to enable
458the support for East Asian languages. Note you could enable this feature
459in the configuration permanently.
460This option is not enabled by default as it makes the program a bit slower.
461There is an entry in the `FAQ`_ with more information on this regard.
462
463Files name encoding
464-------------------
465Since v3.0, *lfm* uses UTF-8 encoding.
466
467Since v2.2, *lfm* was rewritten to always use unicode strings internally,
468but employ terminal encoding (f.e. UTF-8) to interact with the user in
469input forms, to display contents, and to pass commands to run in shell.
470
471When *lfm* detects a file with invalid encoding name it asks the user to
472convert it (can be automatic with the proper option in the configuration).
473If not converted, *lfm* will display the file but won't operate on it.
474
475Virtual File Systems (VFS)
476--------------------------
477You can navigate inside some special files (known as vfs files in *lfm*)
478just *entering into* them (press *enter* or *cursor_right* when the
479cursor bar is over one of these files). By now, supported types are
480`.tar.gz`, `.tar.bz2`, `.tar.xz`, `.zip`, `.rar`, and `.7z` files.
481
482*lfm* even supports navigating nested compressed files (vfs inside vfs)!
483
484The virtual directory name (`path_to_vfs_file#vfs/dir`) is not propagated,
485so the temporary directory (`/tmp/tmpc396zode.lfm/dir`) could be displayed
486in the copy/move/… dialogs or when view/edit/… a file, but this is just
487an estetic issue.
488
489When returning from one of such vfs files, a question dialog appears asking
490to allow you to regenerate the vfs file and update all changes (i.e., it is
491compressed again, so it could be slow in some machines), but *lfm* checks
492if it can do first, to avoid waste of time. This behaviour (rebuild or not
493rebuild, ask it or not) can be modified in the configuration file. By default
494the question is showed but it's set to *not regenerate vfs*.
495
496Note that in the case of `panelize` vfs type (vfs with matched files after
497find/grep), rebuild will cause that all files modifications or deletions
498be translated to the original directory. So be careful!
499
500*lfm* doesn't implement remote vfs such as ssh, ftp, smb, webdav…
501This is a design criterion, we don't want to add external dependencies
502beyond python standard library. If you need to access remote file
503systems you could mount them using something like *fuse* and treat them
504as local directories from inside *lfm*. Look at the `FAQ`_ section to learn how.
505
506Find & grep
507-----------
508You can find and grep for files matching a given pattern (default ``/`` key).
509
510Then you can select some actions to perform:
511
512- ``go``: chdir to the directory containing the selected file
513- ``panelize``: create a VFS with matched files
514- ``view``: view selected file
515- ``edit``: edit selected file
516- ``do``: exec on selected file (output is not captured)
517- ``quit``: quit dialog
518
519Note that in the case of `panelize` vfs, rebuild will cause that all files
520modifications or deletions be translated to the original directory.
521So be careful!
522
523Filters
524-------
525Filters can be used in tabs to hide some files or directories from the view.
526
527Use ``Ctrl-f`` to edit current filter.
528You could see some indication on the frame of pane at the top-right position:
529for example ``.f`` would mean dotfiles are shown (``.``) and there is an active
530filter (``f``).
531
532The filters are a property of a tab, so they remain active even when chdir.
533If you what to disable, edit and delete. The default blank filter is the same
534as ``!*``, i.e. don't hide anything, show all files and directories.
535
536Filters can look complex at first sight, but just remember a filter defines
537the files to hide. They are implemented as `globs`.
538Some examples:
539
540- ``*.png,*.jpg``: hide all PNG and JPEG files
541- ``*.jpg,!*shot*``: hide all JPEG files except those with 'shot' in the name
542- ``*,!*py``: hide all except python source files
543
544Bookmarks
545---------
546The user can define up to 35 bookmarks, which are associated to characters
547`0-9`, `a-z`. Upper and lower variant of a letter represent the same bookmark.
548
549From the main interface use ``B`` key and then select a letter to set a
550bookmark for current directory. Later press ``b`` and this same character
551to go back to the stored path.
552``Ctrl-d`` allows to select the bookmark from a list.
553
554Note you can insert a bookmark path in `EntryLine` widgets or `PowerCLI`.
555
556Move files and directories
557--------------------------
558You can choose between 2 different functions to move files and directories:
559
560- ``move_file``: old implementation
561- ``move_file2``: alternative version using `shtutil.move` instead of
562 copy & delete. Faster but less control of errors. Default
563
564Choose the one you prefer and associate it with the `F6` (default key)
565in the key bindings file.
566
567Some historical notes
568---------------------
569**[These comments are probably not necessary nowdays, but I keep them here anyway.]**
570
571Since version 0.90, *lfm* needs ncurses >= v5.x to handle terminal resizing.
572
573Python v2.5+ and ncurses v5.4+ to use wide characters.
574
575Note that python curses module should be linked against ncursesw library
576(instead of ncurses) to get wide characters support. This is the usual case
577in later versions of Linux distributions, but maybe not the case in older
578Linux or other UNIX platforms. Thus, expect problems when using multibyte
579file names (f.e. UTF-8 or latin-1 encoded) if your curses module isn't
580compiled against ncursesw. Anyway, I hope this issue will disappear with new
581releases of those platforms eventually.
582
583Consult `Files name encoding`_ section below for more information
584about support of different encodings.
585
586
587PowerCLI
588========
589*PowerCLI* is a command line interface with advanced features.
590To show it press ``Ctrl-x``, and same again to hide, ``ENTER`` to run.
591Line contents are restored next time PowerCLI is showed.
592
593Some features:
594
595- uses *EntryLine*, so the same key bindings are available.
596 You can press ``Ctrl-v`` to paste file name for instance
597- completion (``Ctrl-t`` or ``tab`` key), both for system programs or path
598 files and directories
599- loops to run the same command for all the selected files
600- variable substitution
601- can execute python code
602- persistent history between sessions
603- faster than opening a shell (``Ctrl-o``)
604
605*lfm* waits until the command is finished, showing output or error.
606You can stop the command if it seems to run forever.
607
608To run a command in background just add a ``&`` at the end of the command.
609This is useful to open a graphical program and come back to *lfm* quickly.
610But note you won't get any feedback about the command, even if it has been
611able to run or not.
612
613If the program you want to run needs the terminal (less, vim, emacs -nw…),
614add ``$`` at the end of the command to let *lfm* know it must temporary free
615the terminal. Not passing it will fill the screen with garbage.
616
617Variables substitution
618----------------------
619There are a lot of variables you can use to simplify your command typing.
620Specially useful in loops to apply the same command to many files.
621
622- ``$f``: file name including extension
623- ``$v``: same than ``$f``
624- ``$E``: file name without extension
625- ``$e``: extension
626- ``$p``: active directory
627- ``$o``: other pane directory
628- ``$b#``: path in bookmark #
629- ``$s``: all selected files, space-separated and enclosed between "
630- ``$a``: all files, space-separated and enclosed between "
631- ``$i``: loop index, starting at 1
632- ``$tm``: file modification date and time
633- ``$ta``: file access date and time
634- ``$tc``: file creation date and time
635- ``$tn``: now (date and time)
636- ``$dm``: file modification date
637- ``$da``: file access date
638- ``$dc``: file creation date
639- ``$dn``: now (only date)
640
641Python execution
642----------------
643You can run a subset of python language code in a sandbox, but note
644this sandbox doesn't allow to import modules or access anything outside
645for security reasons. But **DON'T TRUST IT'S SECURE**.
646
647The sandbox is a very limited environment but powerful enough to satisfy
648common needs, even you can use the variables inside the code.
649
650Code must be enclosed between ``{`` ``}``. You can even use different code chunks
651in the same command. Consult the examples.
652
653Examples
654--------
655* copy current file (or all selected files in a loop) to the other pane path::
656
657 cp $f $o
658
659* move selected files to path stored in bookmark #3 (no loop)::
660
661 mv $s "$b3"
662
663 We have enclosed ``$b3`` between " here in case the path could contain spaces.
664
665* show all python files in a directory::
666
667 find /to/path -name "*.py"
668
669* open current file with `eog` in background and continue inmediately in *lfm*::
670
671 eog [Ctrl-v] &
672
673* find python files containing some special words in the background
674 and redirect output to a file::
675
676 find . -name "*py" -print0 | xargs --null grep -EHcni "TODO|WARNING|FIXME|BUG" > output.txt &
677
678 Note that if you run a command in the background you won't get any feedback
679 by default, that's why we redirect the output to a file.
680
681* edit current file with `vim` in the console::
682
683 vim %F $
684
685 Note you must end the line with a ``%`` if the command will use the terminal.
686
687* convert file (or all selected) to lowercase and change ``.bak`` extension to ``.orig``.
688 F.e., ``FiLeFOO.bak`` => ``filefoo.orig``::
689
690 mv $f {$f.lower().replace('.bak', '.orig')}
691
692* loop over selected files, copy to the other pane path and rename.
693 F.e., if ``/current/path/img1234.jpeg`` is the 13th file in the
694 selection and was created on 2010/07/22 at 19:43:22
695 => ``/other/path/13. 20100722194322 - IMG1234.jpg``::
696
697 cp $f "$o/{'%2.2d. %s - %s' % ($i, $tm.strftime('%Y%m%d%H%S'), $E.upper())}.jpg"
698
699 Yes, a stupid convoluted example, but it clearly shows how powerful *PowerCLI* is.
700 Also observe that as the target file name contain spaces, the whole destination
701 must be surrounded with ".
702
703Random notes
704------------
705* Paths or filenames with spaces or special characters must be enclosed between ".
706 Study last example above
707
708* Loops are only executed with selected files AND at least one of next variables
709 present within the command: ``$f``, ``$v``, ``$F``, ``$E``, ``$i``, ``$tm``,
710 ``$ta``, ``$tc``. Remember ``$a`` or ``$s`` never loop
711
712* Note the differences of running commands with trailing ``&`` vs. ``$`` vs. nothing
713
714* If cursor is at the beginning of line, completion will try system programs.
715 If it is in any other position, it will try files or directories first and
716 if nothing is found then programs
717
718* Although python code is executed inside a sandbox, it's not completely secure.
719 Anyway, it's the same kind of security issues your system is exposed to when
720 shell access is allowed
721
722
723Customization
724=============
725The configuration of *lfm* is stored across some files in the
726`~/.config/lfm` directory. This directory is created the first time
727*lfm* runs, and filled with some files with default settings.
728
729To restore default configuration exit from all instances of *lfm* and
730delete `~/.config/lfm` directory. You could also the command line
731options to restore default configuration, key bindings, or theme.
732
733In next subsections we will discuss the default configuration and the
734meaning of the different options.
735
736Preferences
737-----------
738Program preferences are saved in the ``~/.config/lfm/lfm.ini`` file.
739
740To configure *lfm* go to `General Menu [F9] -> Edit Configuration [c]`
741menu option, or edit this file manually when no instance of the
742program is running.
743
744It contains these parts:
745
746Header
747~~~~~~
748Always the same text. It is used to validate the configuration file::
749
750 ########## lfm - Last File Manager Configuration File v3.x ##########
751
752[Options]
753~~~~~~~~~
754Main settings::
755
756 # automatic_file_encoding_conversion: never = -1, ask = 0, always = 1
757 # sort_type: SortType.none, SortType.byName, SortType.byExt, SortType.byPath, SortType.bySize, SortType.byMTime
758 automatic_file_encoding_conversion: 0
759 detach_terminal_at_exec: 1
760 find_ignorecase: 1
761 grep_ignorecase: 1
762 grep_regex: 1
763 rebuild_vfs: 0
764 save_configuration_at_exit: 1
765 save_history_at_exit: 1
766 show_dotfiles: 1
767 show_output_after_exec: 1
768 sort_mix_cases: 1
769 sort_mix_dirs: 0
770 sort_reverse: 0
771 sort_type: SortType.byName
772 use_wide_chars: 0
773
774* ``automatic_file_encoding_conversion``: Automatically convert filenames when wrong encoding found? Default 0 (no, ask)
775* ``detach_terminal_at_exec``: Detach terminal at execute? Default 1 (yes)
776* ``find_ignorecase``: Ignore case in find? Default 0 (no)
777* ``grep_ignorecase``: Ignore case in grep? Default 1 (yes)
778* ``grep_regex``: Use regex as grep pattern? Default 1 (yes)
779* ``rebuild_vfs``: Rebuild vfs? Useful if automatic in confirmations->ask_rebuild_vfs. Default 0 (no)
780* ``save_configuration_at_exit``: Save configuration at exit? Default 1 (yes)
781* ``save_history_at_exit``: Save history at exit for future sessions? Default 1 (yes)
782* ``show_dotfiles``: Show .files? Default 1 (yes)
783* ``show_output_after_exec``: Show output after exec? Default 1 (yes)
784* ``sort_mix_cases``: Mix upper and lower case files in sort? Default 1 (yes)
785* ``sort_mix_dirs``: Mix files and directories in sort? Default 0 (no)
786* ``sort_reverse``: Reverse sort? Default 0 (no)
787* ``sort_type``: Sort type. Default SortType.byName (sort by name)
788* ``use_wide_chars``: Use wide chars? Default 0 (no)
789
790[Confirmations]
791~~~~~~~~~~~~~~~
792These settings indicate whether the user will be prompted in these actions::
793
794 ask_rebuild_vfs: 1
795 delete: 1
796 overwrite: 1
797 quit: 1
798
799* ``ask_rebuild_vfs``: when abandoning compressed files, prompt if we should
800 rebuild the file in case we've modified contents.
801 Note that in `find/grep panelize` (vfs with matched files) if
802 rebuild, all files modifications or deletions are translated to
803 original directory. So be careful!
804
805[Misc]
806~~~~~~
807Settings which require a string value::
808
809 # diff_type: context, unified, ndiff
810 backup_extension: .bak
811 diff_type: unified
812
813* ``backup_extension``: Backup file extension? Default .bak
814* ``diff_type``: Diff output format? Default unified
815
816[Programs]
817~~~~~~~~~~
818Default programs *lfm* uses to open common file types::
819
820 audio: vlc
821 ebook: FBReader
822 editor: vi
823 graphics: eog
824 pager: less
825 pdf: evince
826 shell: bash
827 video: vlc
828 web: firefox
829
830The applications listed here must be executable programs in your `$PATH`,
831shell alias will not work.
832
833[Files]
834~~~~~~~
835File extensions associated with default programs. Used to color files too.
836See previous subsection::
837
838 archive: 7z, arc, arj, ark, bz2, cab, deb, gz, lha, lzh, rar, rpm, tar, tbz2, tgz, txz, xz, z, zip, zoo
839 audio: au, flac, mid, midi, mp2, mp3, mpg, ogg, wma, xm
840 data: cdx, dat, db, dbf, dbi, dbx, dta, fox, mdb, mdn, mdx, msql, mssql, nc, pgsql, sql, sqlite, ssql
841 devel: ada, asm, awk, bash, c, caml, cc, cgi, cpp, css, diff, el, f, f90, glade, h, hh, hpp, hs, inc, jasm, jav, java, js, lua, m, m4, mak, ml, mli, mll, mlp, mly, pas, pas, patch, php, phps, pl, pm, pov, prg, py, pyw, rb, sh, sl, st, tcl, tk, ui, vala
842 document: 1, abw, bib, djvu, doc, docx, dtd, dvi, gnumeric, ics, info, letter, lsm, mail, man, msg, odc, odp, odt, po, pps, ppt, pptx, rtf, sdc, sdp, sdw, sgml, sxc, sxp, sxw, tex, text, txt, vcard, vcs, xls, xlsx, xml, xsd, xslt
843 ebook: azw, azw3, chm, epub, fb2, imp, lit, mobi, prc
844 graphics: ai, bmp, cdr, dia, dwb, dwg, dxf, eps, gif, ico, jpeg, jpg, omf, pcx, pic, png, rle, svg, tif, tiff, wmf, xbm, xcf, xpm
845 pdf: pdf, ps
846 temp: $$$, bak, tmp, ~
847 video: acc, asf, avi, flv, med, mkv, mol, mov, mp4, mpeg, mpg, mpl, ogv, ogv, swf, wmv
848 web: htm, html, shtml
849
850[Bookmarks]
851~~~~~~~~~~~
852User-defined 35 bookmarks (0-9, a-z). No differences between upper and
853lower character, as they represent the same bookmark. ``/`` initially::
854
855 0: /
856 1: /
857 . . .
858 8: /
859 9: /
860 a: /
861 b: /
862 . . .
863 y: /
864 z: /
865
866[PowerCLI Favs]
867~~~~~~~~~~~~~~~~~~~
868User-defined 10 favourite PowerCLI stored commands::
869
870 0: mv "$f" "{$f.replace('', '')}"
871 1: less "$f" %
872 2: find "$d" -name "*" -print0 | xargs --null grep -EHcni "TODO|WARNING|FIXME|BUG"
873 3: find "$d" -name "*" -print0 | xargs --null grep -EHcni "TODO|WARNING|FIXME|BUG" >output.txt &
874 4: cp $s "$o"
875 5:
876 6:
877 7:
878 8:
879 9:
880
881Key bindings
882------------
883The currently used key bindings for the main user interface are stored
884in the ``~/.config/lfm/lfm.keys`` file.
885To customize select `General Menu [F9] -> Edit keys [k]` from the program
886or if you edit the file directly be sure no instance of *lfm* is running.
887
888Currently, it is not possible to modify the key bindings for the dialogs.
889
890The format is::
891
892 <action>: key_combination_1 key_combination_2 …
893
894Something like ``C-up`` means `Control` & `cursor up` keys pressed
895simultaneously and ``A-s`` means `Alt` & `s` keys pressed simultaneously.
896If the definition contains 2 or more bindings, all of them could be
897used, as is the case with ``C-u`` and ``,`` for `panes_swap` action below.
898
899Consult `Keys shortcuts`_ section for more information.
900
901Default key bindings::
902
903 ########## lfm - Last File Manager - Keys ##########
904
905 [Main]
906 # cursor movement
907 cursor_up: up k
908 cursor_down: down j
909 cursor_pageup: pageup backspace C-p
910 cursor_pagedown: pagedown spc C-n
911 cursor_up10: C-up
912 cursor_down10: C-down
913 cursor_home: home C-a
914 cursor_end: end C-e
915 cursor_goto_file: C-s
916 cursor_goto_file_1char: A-s
917
918 # change dir
919 dir_up: left
920 dir_enter: right enter
921 goto: g
922 bookmark_goto: b
923 bookmark_set: B
924 bookmark_select_fromlist: C-d
925 history_select_fromlist: C-y
926
927 # pane & tabs
928 pane_change_focus: tab
929 pane_other_tab_equal: =
930 panes_swap: C-u ,
931 panes_cycle_view: .
932 refresh: C-r
933 redraw_screen: A-r
934 dotfiles_toggle: C-h
935 filters_edit: C-f
936 sort_files: s
937 show_dirs_size: #
938 tab_new: :
939 tab_close: !
940 tab_left: <
941 tab_right: >
942
943 # selection
944 select: ins
945 select_glob: +
946 deselect_glob: -
947 select_invert: *
948
949 # files
950 rename_file: F2
951 view_file: F3
952 edit_file: F4
953 copy_file: F5
954 move_file2: F6
955 make_dir: F7
956 delete_file: F8
957 exec_on_file: @
958 touch_file: t
959 link_create: l
960 link_edit: L
961 show_file_info: i
962
963 # general
964 find_grep: /
965 show_tree: C-t
966 main_menu: F9
967 file_menu: F12
968 help_menu: h
969 open_shell: C-o
970 toggle_powercli: C-x
971 quit_chdir: q F10
972 quit_nochdir: C-q
973
974Color themes
975------------
976The current theme is stored in the ``~/.config/lfm/lfm.theme`` file,
977where you can adapt the user interface colors to your likings.
978To customize select `General Menu [F9] -> Edit theme [e]` from the program
979or if you edit the file directly be sure no instance of *lfm* is running.
980
981
982To edit this file be sure no instance of *lfm* is running.
983
984Each entry represents a different entity. The format is::
985
986 <item>: foreground_color background_color
987
988or to make an entity adopt the same colors as other previous one::
989
990 <item>: =<previous_item>
991
992Valid colors are: white, black, red, green, yellow, blue, magenta, cyan.
993Can use * before a foreground color to intensify.
994
995Default theme is defined as::
996
997 ########## lfm - Last File Manager - Theme ##########
998
999 # Format is: item: foreground background
1000 # or: item: =previous_item
1001 # Valid colors: white, black, red, green, yellow, blue, magenta, cyan
1002 # Can use * to intensify a foreground color
1003
1004
1005 [Colors]
1006 header: yellow blue
1007 tab_active: yellow black
1008 tab_inactive: =header
1009 pane_active: green black
1010 pane_inactive: white black
1011 pane_header_path: red* black
1012 pane_header_titles: white* black
1013 statusbar: =header
1014 powercli_prompt: blue* black
1015 powercli_text: white black
1016
1017 selected_files: yellow* black
1018 cursor: blue cyan
1019 cursor_selected: yellow* cyan
1020
1021 files_dir: green black
1022 files_exe: red black
1023 files_reg: white black
1024 files_archive: yellow black
1025 files_audio: blue black
1026 files_data: magenta* black
1027 files_devel: cyan black
1028 files_document: blue black
1029 files_ebook: =files_document
1030 files_graphics: magenta black
1031 files_pdf: =files_document
1032 files_temp: white black
1033 files_web: =files_document
1034 files_video: =files_audio
1035
1036 dialog: yellow blue
1037 dialog_title: yellow* blue
1038 button_active: yellow* red
1039 button_inactive: =dialog_title
1040 dialog_error: black red
1041 dialog_error_title: white red
1042 dialog_error_text: white* red
1043 dialog_perms: green* black
1044 selectitem: blue cyan
1045 selectitem_title: red cyan
1046 selectitem_cursor: yellow blue
1047 entryline: yellow* cyan
1048 progressbar_fg: black white
1049 progressbar_bg: white cyan
1050 view_white_on_black: white black
1051 view_red_on_black: red black
1052 view_blue_on_black: blue black
1053 view_green_on_black: green black
1054
1055
1056FAQ
1057===
1058**How and why lfm born?**
1059
1060 Everything is explained in next sections. `list.com` and `midnight commander`
1061 were the muses who guided.
1062
1063**Isn't python slow? why develop lfm on python?**
1064
1065 No. It's fast enough. And programming in python is funny.
1066
1067**Does it work with Python v2.x?**
1068
1069 Not anymore. lfm v3.x is written for Python 3.4+. If you only have
1070 Python 2.x please use old lfm v2.3.
1071
1072**lfm does not change to current directory after quiting**
1073
1074 This can't be made inside the program, but you could get it using
1075 the shell tip mentioned `Installation`_ section.
1076
1077**lfm does not start, shows the message "Terminal to narrow to show contents"**
1078**lfm shows the message "Terminal to narrow to show contents" and quits when resizing**
1079
1080 lfm needs a terminal with 66 columns as mininum.
1081 If the terminal is narrower or you resize it to fewer columns program will
1082 stop inmediately.
1083
1084**Why doesn't lfm implement remote vfs such as ssh, ftp, smb, webdav, ...?**
1085
1086 One of the design goals for *lfm* is simplicity, we don't want to add
1087 external dependencies beyond python standard library. Nevertheless
1088 you can use something like *fuse* to mount those remote volumes anyway.
1089
1090 To use fuse with ssh you need *fuse* and *sshfs* packages installed
1091 on your system::
1092
1093 $ mkdir /mount/point/for_ssh_server
1094 $ sshfs user@ip_or_hostname:/path /mount/point/for_ssh_server
1095
1096 For ftp you need *fuse* and *curlftpfs*::
1097
1098 $ mkdir /mount/point/for_ftp_server
1099 $ curlftpfs ftp://user:password@ip_or_hostname /mount/point/for_ftp_server
1100
1101 For webdav you need *fuse* and *wdfs* or davfs2 (non fuse based)::
1102
1103 $ mkdir /mount/point/for_webdav_server
1104 $ wdfs https://user:password@server.org/webdav_dir /mount/point/for_webdav_server
1105
1106 For smb take a look at *fuse-smb*.
1107
1108 And to umount::
1109
1110 $ fusermount -u /mount/point
1111 $ rm -rf /mount/point
1112
1113**Request: add advanced file rename tool**
1114
1115 Use *PowerCLI*, it's much... uhmmm... powerful!
1116
1117**I don't like the colors of the interface. Can I change the theme?**
1118
1119 Yes!!! lfm v3.x supports color personalization, but only one default
1120 theme is provided.
1121 Customize colors in the file `~/.config/lfm/lfm.theme`.
1122 More information in the section `Color themes`_.
1123 And please share your creations.
1124
1125**Key bindings customization?**
1126
1127 Yes!!! lfm v3.x supports key bindings personalization.
1128 Customize them in the file `~/.config/lfm/lfm.keys`.
1129 More information in the section `Key bindings`_.
1130
1131**Some Chinese, Japanese or Korean files make lfm look ugly or even crash**
1132
1133 Start the program as ``lfm -w`` or enable it by default setting
1134 an option in the configuration file: ``use_wide_chars: 1`` in
1135 section ``[Options]`` (see `[Options]`_ above).
1136
1137 This option is not enabled by default as it makes the program
1138 slower.
1139
1140 The characters of these languages can span over 1 or 2 cells, so
1141 it's not possible for *lfm* to guess the real width they need, it
1142 must be calculated for every string to show.
1143
1144**I can't find pyview anymore**
1145
1146 Starting with version 3.0, *pyview* has been removed from *lfm*
1147 package, and now ``less`` is used as the default file viewer/pager.
1148
1149 Nowdays I use ``emacs`` for almost everything, even as my default
1150 file viewer. You can emulate old *pyview* features easily just
1151 adding next configuration to your ``.emacs`` file::
1152
1153 [...]
1154 (defun eless (&rest args_str)
1155 (interactive)
1156 (let ((args (pop args_str)))
1157 (if (string-match "\\+\\([0-9]+\\)\s+\\(.+\\)" args)
1158 (let* ((line (string-to-number (match-string 1 args)))
1159 (file (match-string 2 args)))
1160 (view-file file)
1161 (goto-line line))
1162 (view-file args))))
1163
1164 (add-hook 'view-mode-hook
1165 '(lambda ()
1166 (define-key view-mode-map "q" 'kill-emacs)
1167 (define-key view-mode-map '[f3] 'kill-emacs)))
1168 (add-hook 'hexl-mode-hook
1169 '(lambda ()
1170 (define-key hexl-mode-map '[f4] 'hexl-mode-exit)))
1171
1172 (global-set-key '[f2] 'toggle-truncate-lines)
1173 (global-set-key '[f3] 'view-mode)
1174 (global-set-key '[f4] 'hexl-mode)
1175 (global-set-key "\C-cn" 'linum-mode)
1176 [...]
1177
1178 create a new executable program ``ve`` with these contents and move it
1179 to any directory in your `$PATH`::
1180
1181 emacs -nw --eval "(eless \"$*\")"
1182
1183 and finally set ``ve`` as your viewer in *lfm* configuration: `pager`
1184 entry under `[Options]` section in ``~/.config/lfm/lfm.ini`` file.
1185
1186 Of course you can substitute that ``emacs`` call with ``emacsclient``
1187 and adapt the code if you run ``emacs`` as daemon.
1188
1189 If you prefer ``vim`` create the ``ve`` file with something like::
1190
1191 vim -u /usr/share/vim/vimXX/macros/less.vim "$*"
1192
1193 where `XX` is the vim version you have, for example `74` for vim 7.4.
1194
1195 In any case note that ``ve`` must be an executable program in your `$PATH`,
1196 a shell alias will not work.
1197
1198**Mouse support? UI to configure settings?**
1199
1200 I'm afraid we speak different languages.
1201
1202**When will be support for internationalization?**
1203
1204 If we are talking about translating *lfm*, the answer is mostly
1205 never. Ncurses programming makes very difficult to control the
1206 length of every text for every possible language translation.
1207
1208 If you mean support for file names in foreign languages and
1209 encodings then it's almost here already.
1210
1211**[Any other question / feature request]**
1212
1213 Consult if it's mentioned in the `<TODO>`_ file and/or send me an email.
1214
1215
1216History
1217=======
1218Many many years ago I began to write a program like this in C, but after
1219some weeks of coding I never finished it… I'm too lazy, yes.
1220Then I saw the light and I started writing *lfm* to learn Python.
1221
1222Code evolved and application got more and more features, used by many
1223people around the world on different UNIX systems.
1224
1225But after the release of version 0.91 (June 2004) they were not more releases.
1226Not that I had stopped working on *lfm*, new code was written, tested,
1227rewritten again… silently… different reasons made me to postpone public
1228releases… refactoring, a new essential feature, source cleaning,
1229a wedding, a child, ahem… code refactoring…
1230
1231Anyway, from now on I'll do my best to release often.
1232
1233
1234Thanks
1235======
1236Thanks are obviously due to the whole python community, specially to GvR
1237(of course! ;-) and all the people who answered my questions in c.l.p.
1238
1239It's a great pleasure to code in a language like this.
1240
1241Alexei Gilchrist, for his cfm program from which I took some ideas.
1242
1243`Midnight Commander <http://www.ibiblio.org/mc/>`_ developers, whose
1244program was the mirror.
1245
1246`Vernon D. Buerg's list.com <http://web.archive.org/web/20070720001132/http://www.buerg.com/about.htm>`_,
1247the best program ever coded (well, just after emacs ;-).
1248Added 2012/06/19: I've just read Buerg died on Dec. 30, 2009. RIP.
1249
1250And also to all the people who have contributed with ideas, reporting
1251bugs and code over these years: Antoni Aloy, Sebastien Bacher, Grigory
1252Bakunov, Greg Bell, Jean-François Bercher, Luigi M. Bianchi, Hunter
1253Blanks, Josef Boehm, Witold Bołt, Fabian Braennstroem, Jason Buberel,
1254Ondrej Certik, Kevin Coyner, Tim Daneliuk, Mike Dean, Arnå DG,
1255Maximilian Dietrich, Christian Eichert, Steve Emms, Murat Erten,
1256Daniel Echeverry, Luca Falavigna, Stephen R. Figgins, f1ufx, Roy
1257Fullmer, Francisco Gama, Vlad Glagolev, Ana Beatriz Guerrero Lopez,
1258Kelly Hopkins, Laurent Humblet, Ibu, Tjabo Kloppenburg, Zoran Kolic,
1259Shantanu Kulkarni, Kurka, Max Kutny, Karol M. Langner, Yu-Jie Lin,
1260Martin Lüethi, Thomas Marsaleix, Mateusz Matejuk, Maurício, James
1261Mills, Oliver Mueller, Bartosz Oler, Piotr Ozarowski, Mikhail
1262A. Pokidko, Jerome Prudent, Mikhail Ramendik, Rod, Daniel T. Schmitt,
1263Chengqi Song, Robin Siebler, Andrey Skvortsov, Espartaco Smith, Jörg
1264Sonnenberger, Jonathan Steel, Martin Steigerwald, Wayne Tan, Joshua
1265Tasker, Tim Terlegård, Jean Terrier, Edd Thompson, Sergey Tkachenko,
1266E.R. Uber, Viktor Vad, Walter van den Broek, Jesper Vestergaard, Xin
1267Wang, Alejandro Weil, Yellowprotoss, Hai Zaar and many others…
1268
1269You have made posible to run *lfm* in all those platforms!
1270
1271
1272.. |date| date:: %a, %d %b %Y - %H:%M:%S
1273