Tfman quick start guide

Maciej Helminiak <tfman.project@opmbx.org>
modified: 2014-07-15



1. Install

Installing Tfman is easy. You can use tarballed sources or - if you are Arch Linux user - AUR repository. Just follow directions at Install.

2. General work flow

Tfman works with textual representation of file system, which is ordinary text. It parses it and performs operations specified by user. To prepare textual representation of part of filesystem you want to work with, Tfman has scan mode.

It follows that three stages are involved: scan filesystem with Tfman, process text any way and parse resulting text with Tfman. It is usually done in one step with tool called Tfm, or with command line tool like sed or awk or inside Vim. However, to illustrate how Tfman works, first, see how it looks in three separate steps:

  1. Create file with textual representation of '/Dir' scanned three levels deep:
      $ tfman /Dir -R=3 > tr.tfm
    
  2. Use sed, vim or any other text processing tool to edit tr.tfm and add actions you want
  3. Parse file (operations will be presented to you and confirmation will be requested):
      $ tfman tr.tfm
    

Obviously there must be more convenient way to use it. There are three basic ways to use Tfman, which are described in further chapters:

3. Non-interactive

Tfman can be used in combination with command-line text processing tools. Lets take Sed fo example.

NOTE:
In each example you can invoke Tfman without piping output to Sed just to take a look how textual representation looks like in that particular case.

This will move all files (and only files, not directories) containig 'tfm' anywhere in the name to common directory. Files may lay anywhere in the given directory tree:

  $ tfman DIR -R -F=name,type | sed 's,\(^|.*tfm.*[^d]$\),\1 >>/tmp/common,' | tfman

You can use -n option to ommit confirmation step or -s option to just see what operations would be performed. These are parsing options and must be appended to second Tfman invokation.

This will move all directories in current directory tree with extension '.tmp' (together with content ofcourse):

  $ tfman DIR -F=name,type -R | sed 's,\(^|.*.tmp/] d$\),\1 >>/tmp/common,' | tfman

This will remove all broken symlinks in whole directory tree:

  $ tfman DIR -R=4 | sed 's,\(^|.*].*!!>.*l$\),\1 *,' | tfman

4. Tfm

Interactively you will use Tfman in combined mode, which joins scanning, editing and parsing in one step. Make sure you have EDITOR shell variable set to your favorite text editor (otherwise default is Vim) and invoke:

  $ tfm DIR -R=3 -C -F=name
NOTE:
Currently Vim and Nano are tested to work with Tfm. If your editor has unusual invokation syntax or does not read standard input stream you may need to modify '/usr/bin/tfm' slightly. Give me a shout about it.

Textual representation of DIR scanned recursively 3 levels deep will be opened in editor. Options are passed directly to Tfman. Option '-C' gives you double names for each entry. '-F' specifies what entry fields you want. Sample of textual representation may look like this:

  # [DIR/] DIR
  | [entry1  ] entry1
  | [entry2  ] entry2
  | [entry3  ] entry3
  | [entry4  ] entry4
  | [entry5  ] entry5
  | [entry6  ] entry6

Now add actions you desire. For example, if you want to rename some files, add move tag '>>' before second name in each line and modify those names afterwards. In the end it should look something like:

  # [DIR/] DIR
  | [entry1  ] >>entry1.jpg
  | [entry2  ] >>entry2.png
  | [entry3  ] >>entry333
  | [entry4  ] >>Dir1
  | [entry5  ] >>Dir2
  | [entry6  ] >>entry6_old
  # [DIR/] >>DIR_NEW_NAME

When you save and quit, Tfman will automatically parse what you have done and ask you for permission to proceed. Note that directory entry was copied to last line. Otherwise it would be renamed as the first and all entry names would became invalid.

Tfman performs the same (!) actions in order of appearance in text. Different actions are performed in fixed order: first every create entry '~' action, then every create symlink action '->', then other actions and remove '*' as last. Consult manpage for actions list.

5. Inside Vim

Omit this chapter if you do not use Vim.

a. Run Vim and issue following command:

  :Tsr . 2

This will scan current directory 2 levels deep and place result in newly opened edit window. This window is now first Tfman window.

Go to empty window below and then:

  :Te

This will mark current window as messages window. You could ommit this step and have message window opened automatically during first parsing command, but this way you have more control where message widnow is. Message window is common for all edit windows in tabpage. You can have more, but only the first one will be used.

  :Tsw /

Will scan root directory and open result in fresh, second edit window.

b. Go to first edit window and add some actions.

For example to change permissions, owners and create some new and delete unneeded files:

  # [.]
   [entry1] :rwxrwx---
   [entry2] user:group:rwxrwx---
   [entry3] user:rwxrwx---
   [entry3] rwxrwx---:group
   [new1] ~
   [new2] ~
   [new3] ~
   [delete_This] *

c. Now use one of following commands:

For more scanning commands consult manpage.

Keys (assuming '\' is your mapleader):

ENTER
scan directory under cursor
-
scan parent of current directory
\[ \] \}
previous/next/refresh current history
\m \c \M \C \r
move, copy, move-overwrite, copy-over, remove entry under cursor
\R
immediately remove entry under cursor
\t
create entry
<C-F> - insert mode mapping
complete file name entered after '>' character

Handy commands:

:Tins PATH
insert PATH under cursor, you can use tab completion with this command, it is handy for inserting file names to text
:The
show history