weex(1)

💖 weex — the manual, bestie edition 💖

part of the General Commands Manual ✨ (weex(1), in case you were wondering which page you're on 🫶)

---

✨ NAME ✨

weex — fast WEb EXchanger, aka a non-interactive FTP and FTPS client 💅

---

🌸 SYNOPSIS 🌸

weex [ Options ] HOSTID [HOSTID...]

---

🦋 DESCRIPTION 🦋

okay so listen. weex is a utility built to automate the whole "remotely maintaining a web page or some other FTP or FTPS archive" situation. fr fr — if you're the maintainer of a web site or archive that has to be administered through FTP/FTPS interaction, this thing lets you largely ignore that process. iconic behavior honestly 👑

here's the vibe: the archive administrator just makes a local directory that serves as an exact model for the offsite data. all your modifications and all your direct interaction happen locally, in that directory structure. that's it. that's the whole thing.

then, whenever the administrator wants to coordinate the data on the remote site with the local model directory, they just run weex and it handles it in the most bandwidth-efficient fashion possible, because it only transfers the files that actually need updating 🧚✨ the program will create or remove files or directories as necessary so the local model gets accurately established on the remote server. no cap.

the mandatory HOSTID argument is the user-defined name that represents a particular FTP account or configuration specified in the ~/.weexrc file 📁 this file — the contents of which are described below — can alternatively be named ~/.weex/weexrc.

you can pass multiple HOSTID arguments to a single weex command btw, and that's supported, so you can affect multiple archives or configurations in immediate succession 🌈

and get this — instead of the actual HOSTID, you can substitute the number representing its relative sequential position in the ~/.weexrc file. the first HOSTID definition is 1, and so on. lowkey genius 🔥

---

💅 OPTIONS 💅

⚠️ heads up bestie: options at the command line take precedence over any specified in the configuration file. command line stays winning 👑

• -d, --debug-config — outputs the configuration of each hosts.
• -D, --debug-ftplib — outputs messages from/to the FTP server. the whole convo, no filter 🙈
• -f, --force — if the caching mechanism is inhibiting the uploading of files that should be transferred, this option will force the actual transfer to always occur. like, always always.
• -h, --help — outputs a usage summary to stdout ✨
• -m, --monochrome — the default mode generates a helpful color coding based on the operation being performed. this option suppresses that. (aesthetic loss tbh, but valid 🎀)
• -r, --rebuild-cache — if the cache file is broken, use this to rebuild it 🔧
• -s, --silent — the default mode outputs a helpful status message for each action taken, including file transfer progress meters. this mode suppresses output 🤫
• -t, --test — weex doesn't modify any remote files/directories. a little dry run moment 🧪
• -V, --version — prints the version of the weex program 💜

---

...and that's where this part wraps, bestie. more coming 🫶

💖 CONFIGURATION FILE 💖

ok so bestie, listen up — this program is built to be non-interactive, meaning it is not gonna stop and chat with you while it runs. so a properly set up configuration file is, like, absolutely essential. no cap. weex goes hunting for it in either ~/.weexrc or ~/.weex/weexrc. ✨

the general format is a bracketed section heading followed by parameters that define that section's configuration. that section name is the exact thing you hand to weex at run time to say which FTP arrangement you wanna update. a parameter is only valid for the most recent section heading that came before it. the one exception? the [default] section, which creates settings for unspecified parameters in every section. and for parameters that accept multiple values, the default section augments any specifically designated values. it's giving teamwork. 💅

lines that begin with the # character are safely ignored as comments. neither section names nor parameter variables are case sensitive in any way. section names can not begin with numbers. some parameters can be assigned multiple values; where that's not possible, the last value is used. to quote special characters, use single quotes (') or double quotes ("). to quote a particular quote symbol, use the other quote. the general syntax format for the config file is:

[hostid1]
        Parameter1 = Value
        # First method for multiple values
        Parameter2 = Value
        Parameter2 = Value
        ...

[hostid2]
        Parameter1 = Value
        # Second method for multiple values
        Parameter2 = {
               Value
               Value
        }
        ...

[default]
        Parameter = Value
        ...

---

🎀 PARAMETER LIST 🎀

these parameters define the properties of a particular host configuration named in brackets. when you're specifying directory names, the trailing / is optional. also, both files and directories (except SrcDir and DestDir) can be specified with shell wildcards. when specifying files, if a file or file pattern is given without a path, it's assumed to be available when encountered in any directory. if it's an explicitly specified path/file combination, the config is available in that directory. files/directories except SrcDir and DestDir can be specified as both absolute path and relative path. but you must specify SrcDir and DestDir as absolute path. when you want to specify /public_html/ignoreme.html as a relative path, you should specify ./ignoreme.html rather than ignoreme.html. when specifying binary states, you may use any of the following: True/False, Yes/No, T/F, 1/0. none of them are case sensitive. slay. 🌈

• AsciiFile — filename patterns that will be transferred using ASCII mode. the default mode for files you don't list here is IMAGE(BINARY) mode. 🦋
• AuthorizationName — if you're using an FTP proxy server that requires challenge/response authorization with the nonstandard AUTHORIZE and RESPONSE commands, set this parameter to your authorization user name (or number). after logging in to the proxy, weex will prompt you with the challenge and read back a response. very main character of it.
• ChangePermission — the access permissions of the files in the directories specified with ChangePermissionDir are changed to this parameter. the format is a three digit octal number. 🔥
• ChangePermissionDir — files in directories assigned to this parameter will have their access permissions changed after sending. specify local directories.
• ChdirAtConnection — set true to change the remote current working directory to DestDir at connection. if the remote current working directory at connection is already DestDir, weex runs faster a bit by setting this parameter to false. default is true. ⭐
• ConvToLower — if set to true, the filenames are converted to lower case before sending. this feature allows interaction with FTP servers that do not support case sensitive filenames. if a naming conflict arises because a lower case name already exists, an error occurs. furthermore, the cache is totally unaware of original uppercase filenames. 💀
• DestDir — destination directory on the remote FTP server where the mirrored information will be sent. this setting corresponds to the pwd command on traditional FTP clients.
• Force — if the caching mechanism is inhibiting the uploading of files that should be transferred, this option will force the actual transfer to always occur if set to true.
• FollowSymlinks — set true to follow symbolic links. default is false. a symbolic link of directory assumes a file whose size is 0 byte at default. 🙈
• FtpPassive — when it's false, weex uses port mode instead of passive mode. if the FTP server doesn't support passive mode, specify false. (it may make transfer slower) default is true. (see also FAQ)
• HostName — hostname to connect to. the ftp:// protocol specifier is implied and shouldn't be used. an IP address is also valid and may save lookup time. ✨
• IgnoreLocalDir — this parameter contains one or more protected local directories that are completely ignored during the transfer process. useful if you want to have subdirectories that are part of a project but don't need to be in the final, online version (i.e., old versions). the way that's so handy.
• IgnoreLocalFile — this parameter contains one or more protected local file specifiers that will be completely ignored during the transfer process.
• IgnoreRemoteDir — this parameter contains one or more protected remote directories that are completely ignored during the transfer process. useful if you want to have other material on the remote FTP site that isn't related to the specific project weex is dealing with. this could include, for example, data administered through a different FTP client or process. 💜
• IgnoreRemoteFile — this parameter contains one or more protected remote file specifiers that will be completely ignored during the transfer process.
• KeepRemoteDir — in their directories, files are not removed when they don't exist in the local directory.
• LogDetailLevel — it specifies how detail level weex records a log at. connection and disconnection message and error messages are always recorded. when weex finishes working correctly, it writes Complete previous disconnection message. if 1 or less, records each connection. if 2, records each directory. if 3 or more, records each file manipulated. default is 1.
• LoginName — login name of the account on the FTP server.
• MaxRetryToSend — when weex fails in sending a file, it retries to send the file. the maximum times of retrying is this parameter. default is 8. specify -1 to stop retrying. 🔥
• Monochrome — the default mode generates a helpful color coding based on the operation being performed. a true setting suppresses that. 😭
• NestSpaces — an integer that controls the indent spacing of the output. the default is 4. if you want to suppress it, specify -1. if you specify 0, weex uses 4. :-)
• OverwriteOK — if the FTP server has trouble overwriting files, set this parameter to false, and each file will be deleted before a new version is put in place.
• Password — plaintext password granting access to the account. note that this file uses no special facilities to safeguard passwords. make sure that the file permissions of a configuration file containing passwords are set conservatively. if they are not, a warning will be issued at execution. if this parameter is not found, weex asks for it on the terminal.

💀 bestie, real talk: this one is plaintext. lock those permissions down or weex will side-eye you with a warning at execution.

• PreservePermissionDir — the access permissions of the files in directories assigned to this parameter will be copied to remote. specify local directories.
• RecordLog — when true, weex creates a log.
• RenameOK — if this parameter is set to true, each file is uploaded under the temporary name weex.tmp, then renamed to its correct name only if the upload succeeds. this avoids the problem of a user getting an incomplete file if he downloads from your Web site while you are uploading to it, and of incomplete files being uploaded if your FTP connection breaks while weex is running. the default is false since some FTP servers might not support renaming. 🎀
• ShowHiddenFile — set true to get hidden files (starting with a dot) on FTP server which doesn't show hidden files by default. default is false.
• Silent — the default mode outputs a helpful status message for each action taken, including file transfer progress meters. a true setting suppresses output.
• SrcDir — top of the source directory tree containing the local copy of the information to be mirrored. this setting corresponds to the lcd command on traditional FTP clients.
• UseSSL — if set to true, use FTPS instead of FTP. explicit AUTH SSL is used to encrypt the FTP session. if it's not supported by the server, weex exits. 🔥
• UseSSLVerify — verify the server certificate. abort if the verification fails. defaults to true.
• UseSSLcafile — path to the file containing CA certificates, for SSL certificate verification. if not specified, defaults to /etc/ssl/certs/ca-certificates.crt. 🦋

✨ EXAMPLES ✨

Okay bestie, here's what a typical .weexrc file might look like — study it, it's giving main character config energy 💅

#-=-=-=-=-=Sample Configuration file=-=-=-=-=-
# My favorite FTP account...
[Ninja]
HostName = ftp.ninja-rights.org
LoginName = chrisxed
Password = '"mYsEcReT!"'
SrcDir = /home/chrisxed/project/weex
DestDir = /
ASCIIfile = *.c
IgnoreLocalDir = /home/chrisxed/project/weex/weex.devel
IgnoreLocalDir = /home/chrisxed/project/weex/weex.old
IgnoreLocalFile = notes2myself.txt
IgnoreRemoteDir = /offsitearchive/

# Another FTP account...
[Veggie]
HostName = ftp.vegetable-advocacy.com
LoginNAME = waxedbean
Password = "X'sBean"
SrcDir = /home/chrisxed/project/legumes
DestDir = /souppot/

# Global configuration settings
[default]
AsciiFile = {
*.htm
*.html
*.txt
*.asc
}
IgnoreLocalFile = {
*.bak
*.tmp
*.swp
}

So with a configuration like this one, running:

$ weex Ninja

would cause the file system assigned to SrcDir to be completely mirrored on the remote server. No crumbs left behind, periodt. 🔥

And running:

$ weex ninja veggie

would make the FTP update happen for the "Ninja" configuration first, and then for the "Veggie" configuration. You could also say it like this instead:

$ weex 1 2

---

🧠 NOTES 🧠

⏰ Timestamp Cache Facility

weex implements a cache of file timestamps from Ver 1.6.0 — which makes updating so much faster when you've got a ton of files, like genuinely obsessed with the speed-up. On top of that, weex also caches directory structure and file names from Ver 2.5.0. So the transfer never gets slow, even if you have many directories and files. Slay. ✨

But lowkey listen: if you change the remote files with another FTP client, or if running weex gets killed, or if weex is terminated by an error, then the cache file will not be correct. The simple solution to this problem is to remove the cache file (located in ~/.weex/weex.cache.HOSTNAME) completely, or to run weex with the option --rebuild-cache.

💻 Tested Operating Systems

• Debian GNU/Linux 2.1
• Red Hat Linux 5.1/5.2/6.0/6.1J
• SuSE Linux 6.1/6.2/6.3
• Linux Mandrake 6.1
• FreeBSD(98) 3.0-RELEASE
• FreeBSD 3.3-RELEASE
• Solaris 2.5.1

---

👑 AUTHOR 👑

This very handy program was written by:

• Yuuki NINOMIYA <gm@debian.or.jp>

The original man page was written by:

• Chris X Edwards <chrisxed@usa.net>

The copyright of this software and documentation belongs to Yuuki NINOMIYA. It is released under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. You can redistribute it and/or modify it under the GPL. 🫶

This software uses shhopt for parsing command line options. Shhopt is released under the Artistic License. You may use it separately under the Artistic License.

---

And that's the whole thing, bestie — YN-cxe dropped this on 2000.05.22, and it's still out here living its weex(1) truth. Go mirror something. Mwah. 💖✨🎀