installx
Copy files into place and set their mode, owner and group.
Mirrors GNU install. Run it as installx, or as gnux installx.
Synopsis
installx [OPTION]... SOURCE... DESTGNU reference
Description
installx copies SOURCE to DEST, or several SOURCE files into the existing directory DEST (or into -t DIRECTORY), and then sets each copy's permission mode (755 unless -m gives another, octal or symbolic) and, with -o and -g, its owner and group. An existing DEST is removed and replaced, not rewritten, so a running program keeps its copy. --backup[=CONTROL] (or -b) first renames each existing destination to a backup: CONTROL simple (or never) appends a suffix, numbered (t) appends .N with N one past the highest already there, existing (nil, the default) numbers the backup only when numbered backups already exist, and none (off) makes none; without a CONTROL the VERSION_CONTROL variable chooses. The suffix is ~, or SUFFIX with -S (which asks for backups by itself), or the SIMPLE_BACKUP_SUFFIX variable. With -d every operand is a directory to create, with its missing parents; the mode applies to the named directories, and parents get 755 minus the umask. -D creates the leading directories of DEST (or the -t directory) first. -T treats DEST as a file even if it is a directory. -C leaves a destination alone when it already has the same content, mode, owner and group. -p gives each copy its source's modification time (the access time is set to the same value). -v reports each file and directory. -s is accepted, but stripping symbol tables needs a strip program, so it only warns that files are installed unstripped. -c is accepted and ignored, as in GNU. -D also answers to the gnux long name --create-leading. A symbolic -m starts from no permissions (u=rwx,go=rx is 755), as GNU install does. On a terminal, gnux's terminal view colors the -v report: the verb (removed, created, renamed), each quoted name and the arrows, in the theme --theme or GNUX_THEME names; the words are GNU's, and piped or redirected output is never colored (--pretty=never or GNUX_PRETTY=never turns it off).
Permissions
Needs read permission on each SOURCE and write and search permission on the destination directory. Setting the owner with -o needs root, and setting the group with -g needs ownership of the file and membership of the group. Off Unix, -o and -g accept numeric IDs only and fail with 'Operation not supported', only the read-only attribute of a mode is representable, and -C therefore always reinstalls.
Use cases
- Installing a built binary into a bin directory with the right mode in one step.
- Writing a Makefile
installtarget that works the same on Linux, macOS and Windows. - Creating a directory tree with an exact mode with
-d. - Deploying configuration files readable by their owner only with
-m600. - Placing a file into a path whose directories may not exist yet with
-D. - Avoiding needless rewrites (and changed timestamps) of unchanged files with
-C. - Setting ownership of system files during packaging with
-oand-g. - Logging what a deployment copied with
-v.
Flags
--backup CONTROL[="$VERSION_CONTROL"] make a backup of each existing destination file; CONTROL is none (off), simple (never), existing (nil) or numbered (t)
-b, --backup-default like --backup but does not accept an argument
-C, --compare compare content of source and destination files, and if no change to content, ownership, and permissions, do not modify the destination at all
-c, --copy ignored; for compatibility with old Unix versions of install
-D, --create-leading create all leading components of DEST except the last, or all components of --target-directory, then copy SOURCE to DEST
-d, --directory treat all arguments as directory names; create all components of the specified directories
-g, --group GROUP set group ownership, instead of process' current group, to GROUP
--help display this help and exit
-m, --mode MODE set permission mode (as in chmod) to MODE, instead of rwxr-xr-x
-T, --no-target-directory treat DEST as a normal file
-o, --owner OWNER set ownership (super-user only) to OWNER
-p, --preserve-timestamps apply access/modification times of SOURCE files to corresponding destination files
--pretty WHEN[="always"] the gnux terminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal only), or 'never'; GNUX_PRETTY sets the default
-s, --strip strip symbol tables (not supported: warns and installs unstripped)
-S, --suffix SUFFIX override the usual backup suffix, '~', with SUFFIX
-t, --target-directory DIRECTORY copy all SOURCE arguments into DIRECTORY
--theme NAME color the view with the built-in theme NAME (gnux theme picks and saves one); GNUX_THEME sets the default
-v, --verbose print the name of each created file or directory
--version output version information and exitExamples
Install a binary with mode 755
installx bin/gnux /usr/local/bin/gnuxInstall several files into a directory
installx a.sh b.sh ~/binInstall a configuration file readable by its owner only
installx -m 600 app.conf ~/.config/app/app.confUse a symbolic mode
installx -m u=rw,go=r README.md /opt/app/README.mdCreate directories with a given mode
installx -d -m 750 /srv/app/logs /srv/app/dataCreate the leading directories of the destination
installx -D app.conf out/etc/app/app.confInstall into a target directory, creating it first
installx -D -t out/bin build/*Report what is installed
installx -v -t ~/bin tool1 tool2Leave unchanged files untouched
installx -C -m 644 docs/*.md /usr/share/doc/app/Keep the source's modification time
installx -p data.db backup/data.dbSet the owner and group (as root)
sudo installx -o root -g wheel -m 755 gnux /usr/local/bin/Install to a file name even if a directory of that name exists (an error then)
installx -T build/app dist/appAn install step in the portable gnux shell
gnux shell -e -c 'installx -D -m 644 site/index.html public/index.html'Install a new binary but keep numbered copies of the ones it replaces
installx --backup=numbered -m 755 build/tool /usr/local/bin/toolOptions
Each option has a page of its own, with its usage and examples.
- --backup: Make a backup of each existing destination file; CONTROL is none (off), simple (never), existing (nil) or numbered (t).
- -b, --backup-default: Like
--backupbut does not accept an argument. - -C, --compare: Compare content of source and destination files, and if no change to content, ownership, and permissions, do not modify the destination at all.
- -c, --copy: Ignored; for compatibility with old Unix versions of
install. - -D, --create-leading: Create all leading components of DEST except the last, or all components of
--target-directory, then copy SOURCE to DEST. - -d, --directory: Treat all arguments as directory names; create all components of the specified directories.
- -g, --group: Set group ownership, instead of process' current group, to GROUP.
- -m, --mode: Set permission mode (as in
chmod) to MODE, instead of rwxr-xr-x. - -T, --no-target-directory: Treat DEST as a normal file.
- -o, --owner: Set ownership (super-user only) to OWNER.
- -p, --preserve-timestamps: Apply access/modification times of SOURCE files to corresponding destination files.
- --pretty: The
gnuxterminal view WHEN: 'always' (the default when WHEN is omitted), 'auto' (the default: on a terminal only), or 'never'; GNUX_PRETTY sets the default. - -s, --strip: Strip symbol tables (not supported: warns and installs unstripped).
- -S, --suffix: Override the usual backup suffix, '~', with SUFFIX.
- -t, --target-directory: Copy all SOURCE arguments into DIRECTORY.
- --theme: Color the view with the built-in theme NAME (
gnuxtheme picks and saves one); GNUX_THEME sets the default. - -v, --verbose: Print the name of each created file or directory.
Exit status
| Status | Meaning |
|---|---|
| 0 | success: every operand was processed |
| 1 | failure: an operand could not be processed (diagnosed on standard error), or a command-line mistake |
Help in the terminal
installx --help # options, first examples, exit status
gnux help installx # this page: the full manual
gnux help installx --OPTION # one option in depth, with its examples