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

 ZTreeMac is ZTreeWin for the Mac: the same program, built from the same
 source, running in a terminal window (Terminal, iTerm2, kitty...).  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 the Mac, and what of
 ZTreeWin is not there.

 This is a beta of the terminal version.  A Mac app with its own window
 is planned.  Please report problems to Zedtek with the version
 (ztree --version), your macOS version and your terminal.


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

 - A Mac with Apple silicon (M1 or later), running macOS 27 or newer.

 - A terminal window 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:
     OpenSSL 3 (brew install openssl@3)  FTPS sites at the Log prompt (F6)
     an editor in $VISUAL/$EDITOR        Edit (nano when neither is set)


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

 ZTreeMac comes as one archive, ztreemac-2.9.11-arm64.tar.gz.  There is no
 installer and nothing is installed outside the folder you choose; ZTreeMac
 needs no administrator password.

 1. Unpack it in Terminal, and move the folder where you want it.  It must
    be a folder you can write to, because ZTreeMac 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:

        cd ~/Downloads
        tar -xzf ztreemac-2.9.11-arm64.tar.gz
        mv ztreemac-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.  ZTreeMac's own 7-Zip needs
    neither.

 2. ZTreeMac is not yet signed and notarized by Apple, so macOS refuses
    to run a copy downloaded with a web browser ("cannot be opened because
    the developer cannot be verified").  Clear the download mark once:

        xattr -dr com.apple.quarantine ~/ztree

    (A copy fetched with curl has no such mark.)

 3. Put ztree on your PATH, and add a shell function for Alt-Quit (exit to
    the current directory).  Add these two lines to ~/.zshrc (zsh is the
    Mac's shell; for bash use ~/.bash_profile), and open a new window:

        export PATH="$HOME/ztree:$PATH"
        ztree() { command ztree "$@"; . ~/ztree/ztlin.sh; }

    ZTreeMac 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, clear its download mark, 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
 and the two lines in ~/.zshrc.

 Privacy: macOS asks the first time a program in your terminal reads the
 Desktop, Documents or Downloads folder, a removable disk or a network
 volume; allow it, or the folder logs as empty or with errors.  Some
 folders (other users', ~/Library, Mail, Safari) need Full Disk Access
 for the terminal app: System Settings > Privacy & Security > Full Disk
 Access.


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

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

 Alt is the Option key, once the terminal is told to send it as Alt:

 - Terminal: Settings > Profiles > Keyboard, "Use Option as Meta key".
 - iTerm2: Settings > Profiles > Keys, Left (and Right) Option key: Esc+.
 - kitty: add "macos_option_as_alt yes" to ~/.config/kitty/kitty.conf.

 The function keys: macOS uses F1-F12 for brightness, volume and the like
 unless System Settings > Keyboard > Keyboard Shortcuts > Function Keys
 has "Use F1, F2, etc. keys as standard function keys" on (or hold fn).
 macOS also keeps some keys for itself: Ctrl-Left/Right and Ctrl-Up/Down
 (Mission Control and Spaces) and F11 (Show Desktop) among them; turn off
 the ones you want ZTree to have in System Settings > Keyboard > Keyboard
 Shortcuts.  Keyboards without them use fn-Up/Down for PgUp/PgDn and
 fn-Left/Right for Home/End.

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

 - kitty, WezTerm 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.

 - iTerm2 and Terminal pass most of them; Ctrl-Shift-letter arrives as
   Ctrl-letter, and Shift-PgUp/PgDn are the terminal's own.

 - Windows Terminal and the Windows console window, with ssh from Windows:
   ZTreeMac 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.

 - tmux: set "extended-keys on" for the Ctrl-Shift and Ctrl-Enter keys,
   and "mouse on" for the 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: clicks, double clicks, dragging and the wheel.  To
 select text with the mouse for the terminal's own Cmd-C, hold Fn in
 Terminal, Option in iTerm2, or Shift in kitty.

 Using kitty

 kitty (https://sw.kovidgoyal.net/kitty) gives ZTreeMac 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.  Install it from
 its web site, or with Homebrew:

        brew install --cask kitty

 Then, in ~/.config/kitty/kitty.conf:

 - Option as Alt:

        macos_option_as_alt yes

 - kitty keeps some Ctrl-Shift and Cmd keys for itself (Ctrl-Shift-T a
   new tab, Ctrl-Shift-Enter a new window, and more), so ZTree never sees
   those.  To give the Ctrl-Shift ones to ZTree:

        kitty_mod ctrl+alt+shift

   which moves kitty's own shortcuts to Ctrl-Option-Shift.  Cmd-C and
   Cmd-V still copy and paste.

 - To open kitty at ZTree's size:

        remember_window_size  no
        initial_window_width  120c
        initial_window_height 43c

   (c: columns and lines, not pixels).

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

 Start ZTreeMac in a kitty window of its own with "kitty ztree" (Homebrew
 puts the kitty command on the PATH), or run ztree in any kitty window.


 How ZTreeMac differs from ZTreeWin│
 ──────────────────────────────────┘

 Paths and drives

 - Paths are shown and typed the Mac (Unix) way: /Users/kim/Documents,
   ~/Desktop.  A typed path may start with / or ~/; a Windows-style
   X:\path is still accepted.

 - There are no drive letters to see.  The startup disk (/) and each
   disk, USB stick, disk image and network share mounted under /Volumes
   are ZTree's "drives" inside, and the volume line shows the mount
   point and file system type (APFS, HFS, MSDOS, EXFAT, SMBFS...).
   macOS's own hidden system volumes are left out.  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
   mount_smbfs mounts: the Keychain's password first, then ZTree asks
   for a user and password, and Alt-Release unmounts it again.  A share
   the Finder has mounted already is used as it is.

 - Apps (.app) and other packages, which the Finder shows as single
   files, are folders, and ZTree shows them as folders you can go into.

 - ZTreeMac compares names case-sensitively, as on Linux.  Most Mac disks
   are not case-sensitive (readme.txt and README.TXT cannot both exist),
   so this matters mainly on case-sensitive volumes.  File specs (*.txt),
   sorting and searches ignore case, as in ZTreeWin.

 - Hidden files are those whose names start with a dot.  Files the
   Finder hides with the hidden flag are not shown as hidden yet.

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

 - Accented names: macOS may store an accented letter as two characters
   (e + accent).  Such names show correctly, but may not sort or compare
   equal to the same name typed as one character.

 Attributes become permissions

 Windows' Read-only, Archive, System and Hidden attributes ("rash") do not
 exist on the Mac.  ZTreeMac 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).

 - The Finder's Locked flag and hidden flag are not shown or changed yet;
   use chflags (uchg, hidden) in the shell.

 Copying

 - Copy and Move between disks keep the file's contents, mode and times,
   but not yet its extended attributes: Finder tags and comments, and
   resource forks are left behind.  Use the Finder or "cp -p" (or ditto)
   for files where these matter.  Moving within one disk keeps
   everything.

 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, top) work.  ZTree waits for a key
   afterwards, so the output can be read.  A path ZTree puts into a
   command line is the Mac path, quoted.  Mac commands work there too:
   "open -a TextEdit", "open ." (the folder in the Finder), "qlmanage -p"
   (Quick Look).

 - Open uses the Mac's open command: the program the Finder has for that
   kind of file (Get Info, "Open with" sets it).  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: open -a 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.

 - Edit uses $VISUAL, else $EDITOR, else nano (vi if it is missing),
   unless an editor is set in Alt-F10.  To edit in TextEdit, set the editor to "open -e -W".
   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 ("open -e" without -W does not wait).

 - JFC compares with "diff -u" in place of TFC.  Any other compare program
   can be set in Alt-F10 (for example "opendiff" with Xcode installed).

 - ARCHIVER.BB2's entries are Windows programs, and are used only if
   those programs exist on your PATH under the same names.  ZTreeMac's own
   7-Zip (7z.so) lists, views and extracts 7z, zip, rar, tar, gz, bz2, xz,
   cab, lzh, iso, dmg 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, with the Mac's clipboard (pbcopy and pbpaste): what ZTreeMac
 copies Cmd-V pastes elsewhere, and Shift-Ins pastes what was copied
 with Cmd-C.  Paths are copied as the Mac shows them; files copied as
 files (F2 at Ctrl-Ins) go as their paths, a line each.

 A copy also goes to the clipboard of the terminal's machine (OSC 52), so
 over ssh from Windows Terminal it lands on the Windows clipboard (kitty,
 WezTerm, iTerm2 and xterm take it too; tmux: set-clipboard on).  Over
 ssh, paste text from elsewhere with the terminal's own paste.

 Other differences

 - 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.


 Not available in ZTreeMac│
 ─────────────────────────┘

 These ZTreeWin features depend on Windows, or are not done on the Mac
 yet, and are not in this version:

 - The Recycle Bin: where ZTreeWin would use it, this beta uses a Linux
   Trash folder (~/.local/share/Trash), which the Finder does not show,
   not the Mac's Trash.  Deleted files can be found there.

 - 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 connect to a server in the Finder (Cmd-K)
   and log its volume under /Volumes.

 - MTP drives (phones and cameras through mtp://), which use Windows
   Portable Devices.

 - Wash disk's NTFS parts, 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 the Mac.


 Files│
 ─────┘

 Files in the archive:

   ztree               - The main ZTreeMac 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.dylib    - PCRE2 libraries for F7 Regex.
   libpcre2-16.dylib
   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 ZTreeMac 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│
 ───────────┘

 "Mac" and "macOS" (tm) are registered trademarks of Apple Inc.
 "Windows" (tm) is a registered trademark of Microsoft Corporation.
 "XTreeGold" (tm) is a registered trademark of Symantec, Inc.

 ZTreeMac 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).
