  ┌───────────────────────────────────────────────────────────────────╗
  │                                                                   ║ █
  │                         Z T r e e L i n                           ║ █
  │                      File Manager for Linux                       ║ █
  │                                                                   ║ █
  │                           Version 2.9.11                          ║ █
  │                                                                   ║ █
  │              Copyright (c) Zedtek, Inc. 1996 - 2026               ║ █
  │                                                                   ║ █
  │                 Home Page: https://www.ztree.com                  ║ █
  │                                                                   ║ █
  └═══════════════════════════════════════════════════════════════════╝ █
   ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

 ZTreeLin is ZTreeWin for Linux: the same program, built from the same
 source, running in a terminal.  The keys, menus, help file (F1),
 configuration (Alt-F10) and file formats (ZTW.INI, ZTW.HST, ZTW.ZAM,
 macros) are ZTreeWin's.  This file covers what is different: how to
 install it, how it fits Linux, and what of ZTreeWin is not there.

 This is a beta.  Please report problems to Zedtek with the version
 (ztree --version) and your distribution and terminal.


 Requirements│
 ────────────┘

 - 64-bit Linux on x86-64 (Intel/AMD) with glibc 2.38 or newer: Ubuntu
   24.04 or newer, Debian 13, Fedora 39 or newer, or another distribution
   of that age.  Older distributions (Ubuntu 22.04, Debian 12, RHEL 9) do
   not run this build.

 - Or 64-bit Linux on ARM (aarch64) with glibc 2.35 or newer: a Raspberry
   Pi 3, 4, 5 or Zero 2 W running 64-bit Raspberry Pi OS (Bookworm or
   newer), or another 64-bit ARM distribution of that age.  32-bit
   Raspberry Pi OS does not run it.

 - A terminal at least 96 columns wide.  The configuration program
   (Alt-F10) needs 80 x 34.  kitty is the recommended terminal: it passes
   every ZTree key.  See "Your terminal" below.

 - Optional, for the commands that use them:
     xdg-open (package xdg-utils)  Open, for a file's own program
     diff                          JFC compare (usually installed)
     OpenSSL (libssl)              FTPS sites at the Log prompt (F6)
     gio (gvfs, gvfs-backends)     SMB shares at the Log prompt (F6)
     wl-clipboard (Wayland), or    The desktop's clipboard (see "The
       xclip or xsel (X11)           clipboard" below)
     an editor in $VISUAL/$EDITOR  Edit (the system's editor, nano or vi
                                   when neither is set)


 Installation│
 ────────────┘

 ZTreeLin comes as one archive for each kind of processor: x86_64 for
 Intel and AMD, aarch64 for 64-bit ARM (ztreelin-2.9.11-aarch64.tar.gz
 for the Raspberry Pi).  "uname -m" prints which one you have.  There is
 no installer and nothing is installed outside the folder you choose;
 ZTreeLin needs no root access to run.

 1. Unpack it, and move the folder where you want it.  It must be a folder
    you can write to, because ZTreeLin keeps its settings and history
    there (ZTW.INI, ZTW.HST and the rest, as ZTreeWin does in its own
    folder).  ~/ztree is a good choice:

        tar -xzf ztreelin-2.9.11-x86_64.tar.gz      (or -aarch64)
        mv ztreelin-2.9.11 ~/ztree

    Keep the files together: ztree looks for ztree-cfg, 7z.so, the
    libpcre2 libraries, ZTW.HLP and ARCHIVER.BB2 in its own folder.

    ARCHIVER.BB2 is supplied as ARCHIVER.BB_, so that it does not
    replace one you already have.  If you have none, or wish to use the
    supplied one, rename it to ARCHIVER.BB2.  ZTreeLin's own 7-Zip needs
    neither.

 2. Put ztree on your PATH, for example with a link from ~/.local/bin
    (most distributions have that on the PATH already):

        mkdir -p ~/.local/bin
        ln -s ~/ztree/ztree ~/.local/bin/ztree

    The link is fine: ztree finds its own folder through it.

 3. For Alt-Quit (exit to the current directory), add a shell function to
    ~/.bashrc (or ~/.zshrc), and open a new terminal:

        ztree() { command ztree "$@"; . ~/ztree/ztlin.sh; }

    ZTreeLin cannot change the directory of the shell that started it.
    On exit it writes ztlin.sh, holding a "cd" for Alt-Quit and Ctrl-Quit
    (empty for a plain Quit), and the function runs it.  This takes the
    place of ZTWIN.BAT.

 4. Run ztree.  The first time, the configuration program (Alt-F10) may
    open; press F3 there to save, even with no changes.

 Registered users copy their ZTW.KEY into the ztree folder.

 Moving over from ZTreeWin: ZTW.INI, ZTW.HST, ZTW.ZAM, ZCOLORS.INI and
 your .ztm macros can be copied from ZTreeWin's folder as they are; the
 files are the same on both.  Paths saved in them (the history, Treespec,
 menu commands) are Windows paths and need retyping or editing.

 To upgrade, unpack the new version and copy its files over the old
 folder's; your ZTW.INI, ZTW.HST and other files are not in the archive
 and are left alone.  To uninstall, delete the folder, the link and the
 shell function.


 Your terminal│
 ─────────────┘

 ZTreeLin draws its screen in the terminal it is started in, and takes its
 size from it: make the window larger or smaller and ZTreeLin follows.
 Alt-F10's window size and position settings do not apply.

 ZTree uses a great many Alt, Ctrl and Shift combinations, and terminals
 differ in which of them they can pass on:

 - kitty, WezTerm, foot and Ghostty (the kitty keyboard protocol) pass
   them all, including Alt or Ctrl held alone for the Alt and Ctrl menus
   and the keypad's own + and - keys.  These are the best choice.

 - xterm passes almost all of them, less Shift-PgUp/PgDn and Shift-Ins,
   which xterm keeps for itself.

 - Windows Terminal and the Windows console window, with ssh from Windows:
   ZTreeLin asks them for Windows' own key records, so the keys come as
   in ZTreeWin - Ctrl-Enter apart from Ctrl-J, and Alt or Ctrl held alone
   for the Alt and Ctrl menus.

 - GNOME Terminal, Konsole and other VTE terminals: Ctrl-Shift-letter
   arrives as Ctrl-letter, and the desktop may take some keys (Alt-F4,
   Ctrl-Alt-F1..F12).

 - tmux: set "extended-keys on" for the Ctrl-Shift and Ctrl-Enter keys,
   and "mouse on" for the mouse.

 - The Linux text console: F1-F12, Shift-F1..F8 and unmodified cursor
   keys only; no mouse.

 Where the Alt and Ctrl menus cannot be shown by holding the key down,
 press F4 to cycle the Normal, Ctrl and Alt menus, as in ZTreeWin.
 "ztree --keys" shows what your terminal sends for each key you press.

 The mouse works in every terminal except the Linux console: clicks,
 double clicks, dragging and the wheel.  Text the terminal selects with
 the mouse (usually with Shift held) is the terminal's own.

 Using kitty

 kitty (https://sw.kovidgoyal.net/kitty) gives ZTreeLin the full keyboard,
 as in ZTreeWin: every Alt, Ctrl and Shift combination, the Alt and Ctrl
 menus while the key is held, and the keypad's own keys.  Most
 distributions package it:

        sudo apt install kitty          (Ubuntu, Debian)
        sudo dnf install kitty          (Fedora)

 Start ZTreeLin in a kitty window of its own with "kitty ztree", or run
 ztree inside any kitty window.

 - kitty keeps some Ctrl-Shift keys for itself (Ctrl-Shift-C/V copy and
   paste, Ctrl-Shift-T a new tab, Ctrl-Shift-Enter a new window, and
   more), so ZTree never sees those.  To give them to ZTree, add to
   ~/.config/kitty/kitty.conf:

        kitty_mod ctrl+alt+shift

   which moves kitty's own shortcuts to Ctrl-Alt-Shift.

 - To open kitty at ZTree's size, add for example:

        remember_window_size  no
        initial_window_width  120c
        initial_window_height 43c

   (c: columns and lines, not pixels).

 - kitty sets COLORTERM=truecolor, so ZTreeLin draws in 24-bit colour.

 - Over ssh, ZTreeLin itself needs nothing more, but programs it runs on
   the other machine (vi, less) need kitty's terminal description there:
   connect with "kitty +kitten ssh host", which copies it, or install the
   kitty-terminfo package on that machine.


 How ZTreeLin differs from ZTreeWin│
 ──────────────────────────────────┘

 Paths and drives

 - Paths are shown and typed the Linux way: /home/kim/src, ~/docs.  A
   typed path may start with / or ~/; a Windows-style X:\path is still
   accepted.

 - Linux has one tree, so there are no drive letters to see.  Each mount
   (/, /home if it is separate, /mnt/..., /media/..., /run/media/...) is
   one of ZTree's "drives" inside, and the volume line shows its mount
   point and file system type (EXT4, BTRFS, VFAT...).  To choose the
   mounts yourself, create ~/.config/ztree/drives with one "X: /path" per
   line (# starts a comment); only the mounts listed there are used.

 - Log (L) asks for a path, not a drive letter: "LOG path:".  Type a
   path, ~, a name under the current directory, or *.  ZTree logs the
   mount holding it and goes to that directory.  F6 there logs an FTP
   site, which is shown and typed as its address (ftp://user@host/path),
   or an SMB share (smb://server/share, or //server/share), which gvfs
   mounts: ZTree asks for a user and password when the server wants
   them, and Alt-Release unmounts it again.

 - Names are case sensitive.  readme.txt and README.TXT are two files,
   and both are shown.  File specs (*.txt), sorting and searches still
   ignore case, as in ZTreeWin.

 - Hidden files are those whose names start with a dot.

 - Directories that are symbolic links are always shown, and a recursive
   log (Alt-Log, Ctrl-Log) does not follow them (a link to / or to a
   parent would never end); go into one to log it.

 - File names that are not valid UTF-8 are kept exactly as they are, so
   such files can still be viewed, copied, moved and renamed.

 Attributes become permissions

 Windows' Read-only, Archive, System and Hidden attributes ("rash") do not
 exist on Linux.  ZTreeLin shows and changes the file's permission mode
 instead:

 - The file window shows the mode in octal (644, 755, 600...) in the
   column where ZTreeWin shows "rash".  Files inside an archive have no
   mode and still show "rash".

 - Attributes (A) and tagged Attributes (Ctrl-A) take a mode as chmod
   does: octal ("644", "0755") or symbolic clauses split by commas
   ("u+x", "go-w", "a=rX", "g=u").  "+R" makes the file read-only (no
   write permission for anyone), and "-R" writable again for its owner.
   The prompt reads "Enter a mode (644, u+x, go-w, +R/-R)".

 - Alt-Tag and Alt-Untag by Attributes take a mode test ("u+x" tags files
   their owner can run, "644" files with exactly that mode), and +R/-R
   (read-only or not), +H/-H (dot names) and +J/-J (symbolic links),
   combined with commas.

 - The file information window shows the owner as user:group and the
   mode as ls -l does, with the octal after it (-rwxr-xr-x 0755).

 - Copy keeps the mode and times, and the owner where you are allowed to.
   "Read-only" in ZTree's prompts (Delete, Move, Override) means the
   owner has no write permission.

 Running programs

 - eXecute, the F9 Application Menu and other commands run their command
   lines through /bin/sh, with the terminal handed over to the program,
   so full-screen programs (vim, less, htop) work.  ZTree waits for a key
   afterwards, so the output can be read.  A path ZTree puts into a
   command line is the Linux path, quoted.

 - Edit uses $VISUAL, else $EDITOR, else the system's editor command
   (Debian, Ubuntu and Mint have one: nano unless chosen otherwise), else
   nano, else vi - unless an editor is set in Alt-F10.  Alt-Edit uses
   the same editor unless Alt-F10 sets another.  START in front of a
   program (as in a Windows setting) is dropped: ZTree waits for the
   program, as it must for one in the terminal.  End a command with &
   for a desktop program ZTree should not wait for.

 - Open uses xdg-open: the program your desktop has for that kind of file.
   A file that is itself a program is run: a desktop program (one that
   links X11, Wayland or a toolkit such as GTK or Qt) on its own, as on
   Windows; any other - ztree-cfg, a #! script - on ZTree's own screen, as
   eXecute runs it, since Linux has no new console window to give it.
   ZTree waits for it, then "Press any key".  With no desktop (over ssh)
   a desktop program runs on ZTree's screen too, so its error shows.
   An ext.BAT file in the ztree folder (MKV.BAT for .mkv files, chmod +x)
   runs instead, through /bin/sh: it is a shell script, so the file's
   name is "$1", not %1 - for example: vlc "$1" &
   $1 is the path and name, $3 the folder's path, $4 the name, $5 the
   extension, $6 the folder's name (empty at a drive's root), $7 the
   path and name again and $8 the name with its extension ($2 is ZTree's
   drive letter); "$@" passes them all.  A script with no #! line, or
   #!/bin/sh, runs with sh's word splitting off, so an unquoted $1 stays
   one name even with spaces in it; for any other shell quote it.

 - JFC compares with "diff -u" in place of TFC.  Any other compare program
   can be set in Alt-F10.

 - ARCHIVER.BB2's entries are Windows programs, and are used only if
   those programs exist on your PATH under the same names.  ZTreeLin's own
   7-Zip (7z.so) lists, views and extracts 7z, zip, rar, tar, gz, bz2, xz,
   cab, lzh, iso and the other formats 7-Zip reads, passwords included,
   with no ARCHIVER.BB2 entry.

 The clipboard

 Ctrl-Ins (copy file and directory information), Shift-Ins and Shift-Del
 on input lines, and the viewer's and history's copy commands work as in
 ZTreeWin.  A copy goes to:

 - ZTreeLin's own clipboard, always: copy and paste within ZTreeLin work
   anywhere, over ssh and on the text console too.

 - The desktop's clipboard, through wl-copy/wl-paste (package
   wl-clipboard) under Wayland, or xclip or xsel under X11.  Without
   them, or without a desktop (ssh), ZTreeLin's own clipboard is used.

 - The clipboard of the terminal's machine (OSC 52): over ssh from
   Windows Terminal, a copy lands on the Windows clipboard.  kitty,
   WezTerm, foot, xterm and iTerm2 take it too (tmux: set-clipboard on).

 Shift-Ins pastes the desktop's clipboard where wl-paste, xclip or xsel
 can read it, else ZTreeLin's own.  Terminals don't let a program read
 their clipboard, so over ssh text from elsewhere comes in with the
 terminal's own paste (Ctrl-Shift-V, or a right click in Windows
 Terminal).  Paths are copied as Linux shows them; files copied as files
 (F2 at Ctrl-Ins) go to the desktop as a file list a file manager pastes.

 Other differences

 - Where ZTreeWin uses the Recycle Bin, ZTreeLin uses the desktop's Trash
   (~/.local/share/Trash).

 - Regular expressions (F7 Regex in Search, View and Filter) and View's
   syntax colouring (the Notepad++ colour files in the ztree folder, or
   your own langs.xml/stylers.xml there) work as in ZTreeWin.

 - ZTreeWin's settings that name Windows folders (%APPDATA%, Documents,
   Desktop) use their Linux counterparts: ~/.config, ~/.local/share and
   the XDG folders (~/Documents, ~/Desktop...).


 Not available in ZTreeLin│
 ─────────────────────────┘

 These ZTreeWin features depend on Windows and are not in this version:

 - Printing to a printer: "Windows Drivers", printer ports (LPT1),
   "CLIP:", and Tab to choose an installed printer.  Print to a file
   works; print the file with lp.

 - Shift-F10, Windows' context menu for a file (ZSHELL.EXE).

 - F4 Map to network at the Log prompt: log an SMB share with F6
   (smb://server/share), or mount network shares the Linux way (your
   desktop, or mount -t cifs/nfs) and log their mount point.

 - MTP drives (phones and cameras through mtp://), which use Windows
   Portable Devices.  Your desktop's MTP mounts (gvfs) can be logged as a
   path instead.

 - The NTFS parts of Wash disk (the MFT, compressed and encrypted files),
   and Windows' Compressed and Encrypted attributes.

 - Text search inside Office and PDF documents through Windows IFilters.

 - The DBF viewer (ZTW_VDBF.EXE), TFC (see JFC above), short (8.3) file
   names, junctions, and Windows Terminal colour schemes.

 - Explorer integration (ZTREE.INF, ZTW.INF), the installation program
   and the Windows .ICO files.  Windows .BAT files (ZTWIN.BAT, the sample
   *.BA_ files) have no place on Linux.


 Files│
 ─────┘

 Files in the archive:

   ztree               - The main ZTreeLin program.
   ztree-cfg           - The configuration program used by Alt-F10.
   7z.so               - 7-Zip 26.00's library: archive listing, viewing and
                         extraction.
   7zCon.sfx           - 7-Zip's Windows console SFX module, for Ctrl-F5's Sfx
                         (self-extracting .7z) option.
   libpcre2-8.so       - PCRE2 libraries for F7 Regex.
   libpcre2-16.so
   ZTW.HLP             - The help file accessed with the F1 key.
   ARCHIVER.BB_        - Used by the archiver commands to call archiver
                         programs; rename it to ARCHIVER.BB2 to use it.
   BETA.TXT            - What is new and fixed in each beta version.
   README.TXT          - This file.
   langs.model.xml     - Notepad++'s language and colour definitions, for
   stylers.model.xml     View's syntax colouring.
   LICENSE.7-Zip.txt   - 7-Zip's licence, and notice of ZTree's changes.
   NOTICE.7-Zip.txt
   LICENSE.PCRE2.txt   - PCRE2's licence.
   LICENSE.notepad++.txt - Notepad++'s licence and notice.
   NOTICE.notepad++.txt

 Files ZTreeLin creates in its folder:

   ZTW.INI             - The configuration file saved using Alt-F10.
   ZTW.HST             - The command history file.
   ZTW.KEY             - The registration key provided to registered users.
   ZTW.ZAM             - The application menu file created by the F9
                         command.
   ZTW.ZA$             - A backup of the application menu file.
   ztlin.sh            - The "cd" for Alt-Quit and Ctrl-Quit (see
                         Installation, step 3).
   ZTWFTP.CRT          - FTP site certificates you chose to trust always.

 Elsewhere:

   ~/.config/ztree/drives  - Optional: your own drive list (see Paths and
                             drives).
   ~/.local/share/         - The evaluation lock.


 Other Notes│
 ───────────┘

 "Linux" (tm) is a registered trademark of Linus Torvalds.
 "Windows" (tm) is a registered trademark of Microsoft Corporation.
 "XTreeGold" (tm) is a registered trademark of Symantec, Inc.

 ZTreeLin includes 7-Zip, Copyright (C) Igor Pavlov, licensed under the
 GNU LGPL (see LICENSE.7-Zip.txt and NOTICE.7-Zip.txt), and the PCRE2
 library, Copyright (c) University of Cambridge, licensed under the BSD
 licence (see LICENSE.PCRE2.txt).  The Notepad++ language files are
 Copyright (C) Don Ho, licensed under the GNU GPL (see
 LICENSE.notepad++.txt and NOTICE.notepad++.txt).
