Skip to Content
gnux

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

GNU 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 install target 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 -m 600.
  • 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 -o and -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 exit

Examples

Install a binary with mode 755

installx bin/gnux /usr/local/bin/gnux

Install several files into a directory

installx a.sh b.sh ~/bin

Install a configuration file readable by its owner only

installx -m 600 app.conf ~/.config/app/app.conf

Use a symbolic mode

installx -m u=rw,go=r README.md /opt/app/README.md

Create directories with a given mode

installx -d -m 750 /srv/app/logs /srv/app/data

Create the leading directories of the destination

installx -D app.conf out/etc/app/app.conf

Install into a target directory, creating it first

installx -D -t out/bin build/*

Report what is installed

installx -v -t ~/bin tool1 tool2

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

Set 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/app

An 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/tool

Options

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 --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: 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 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: 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 (gnux theme picks and saves one); GNUX_THEME sets the default.
  • -v, --verbose: Print the name of each created file or directory.

Exit status

StatusMeaning
0success: every operand was processed
1failure: 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

See also

On this page