fileicon/doc/fileicon.md

OSX CLI for managing custom icons for files and folders

<!-- DO NOT EDIT THIS FILE: It is auto-generated by `make update-man` -->

# fileicon(1) - manage file and folder custom icons

## SYNOPSIS

Manage custom icons for files and folders on macOS.  

SET a custom icon for a file or folder:

    fileicon set      <fileOrFolder> [<imageFile>]

REMOVE a custom icon from a file or folder:

    fileicon rm       <fileOrFolder>

GET a file or folder's custom icon:

    fileicon get [-f] <fileOrFolder> [<iconOutputFile>]

    -f ... force replacement of existing output file

TEST if a file or folder has a custom icon:

    fileicon test     <fileOrFolder>

All forms: option -q silences status output.

Standard options: `--help`, `--man`, `--version`, `--home`

## DESCRIPTION

`<fileOrFolder>` is the file or folder whose custom icon should be managed.  
Note that symlinks are followed to their (ultimate target); that is, you  
can only assign custom icons to regular files and folders, not to symlinks  
to them.

`<imageFile>` can be an image file of any format supported by the system.  
It is converted to an icon and assigned to `<fileOrFolder>`.  
If you omit `<imageFile>`, `<fileOrFolder>` must itself be an image file whose
image should become its own icon.

`<iconOutputFile>` specifies the file to extract the custom icon to:  
Defaults to the filename of `<fileOrFolder>` with extension `.icns` appended.  
If a value is specified, extension `.icns` is appended, unless already present.  
Either way, extraction fails if the target file already exists; use `-f` to  
override.  
Specify `-` to extract to stdout.  

Command `test` signals with its exit code whether a custom icon is set (0)  
or not (1); any other exit code signals an unexpected error.

**Options**:

  * `-f`, `--force`  
    When getting (extracting) a custom icon, forces replacement of the  
    output file, if it already exists.

  * `-q`, `--quiet`  
    Suppresses output of the status information that is by default output to  
    stdout.  
    Note that errors and warnings are still printed to stderr.

## NOTES

Custom icons are stored in extended attributes of the HFS+ filesystem.  
Thus, if you copy files or folders to a different filesystem that doesn't  
support such attributes, custom icons are lost; for instance, custom icons  
cannot be stored in a Git repository.

To determine if a give file or folder has extended attributes, use  
`ls -l@ <fileOrFolder>`.

When setting an image as a custom icon, a set of icons with several resolutions  
is created, with the highest resolution at 512 x 512 pixels.

All icons created are square, so images with a non-square aspect ratio will  
appear distorted; for best results, use square imges.

## STANDARD OPTIONS

All standard options provide information only.

* `-h, --help`  
  Prints the contents of the synopsis chapter to stdout for quick reference.

* `--man`  
  Displays this manual page, which is a helpful alternative to using `man`, 
  if the manual page isn't installed.

* `--version`  
  Prints version information.
  
* `--home`  
  Opens this utility's home page in the system's default web browser.

## LICENSE

For license information and more, visit the home page by running  
`fileicon --home`