# salt.modules.mac_brew_pkg

Homebrew for macOS

It is recommended for the `salt-minion` to have the `HOMEBREW_PREFIX` environment variable set.

This will ensure that Salt uses the correct path for the `brew` binary.

Typically, this is set to `/usr/local` for Intel Macs and `/opt/homebrew` for Apple Silicon Macs.

Important

If you feel that Salt should be using this module to manage packages on a minion, and it is using a different module (or gives an error similar to 'pkg.install' is not available), see here.

salt.modules.mac_brew_pkg.available_version(*names, **kwargs)

  This function is an alias of `latest_version`.

  Return the latest version of the named package available for upgrade or installation

  Currently chooses stable versions, falling back to devel if that does not exist.

  CLI Example:

      salt '*' pkg.latest_version <package name>
      salt '*' pkg.latest_version <package1> <package2> <package3>

salt.modules.mac_brew_pkg.hold(name=None, pkgs=None, sources=None, **kwargs)

  Set package in 'hold' state, meaning it will not be upgraded.

  Added in version 3001.

  name

    The name of the package, e.g., 'tmux'

  CLI Example:

  >     salt '*' pkg.hold <package name>

  pkgs

    A list of packages to hold. Must be passed as a python list.

  CLI Example:

      salt '*' pkg.hold pkgs='["foo", "bar"]'

salt.modules.mac_brew_pkg.homebrew_prefix()

  Returns the full path to the homebrew prefix.

  CLI Example:

      salt '*' pkg.homebrew_prefix

salt.modules.mac_brew_pkg.info_installed(*names, **kwargs)

  Return the information of the named package(s) installed on the system.

  Added in version 2016.3.1.

  names

    The names of the packages for which to return information.

  CLI Example:

      salt '*' pkg.info_installed <package1>
      salt '*' pkg.info_installed <package1> <package2> <package3> ...

salt.modules.mac_brew_pkg.install(name=None, pkgs=None, taps=None, options=None, **kwargs)

  Install the passed package(s) with `brew install`

  name

    The name of the formula to be installed. Note that this parameter is ignored if "pkgs" is passed.

    CLI Example:

        salt '*' pkg.install <package name>

  taps

    Unofficial GitHub repos to use when updating and installing formulas.

    CLI Example:

        salt '*' pkg.install <package name> tap='<tap>'
        salt '*' pkg.install zlib taps='homebrew/dupes'
        salt '*' pkg.install php54 taps='["josegonzalez/php", "homebrew/dupes"]'

  options

    Options to pass to brew. Only applies to initial install. Due to how brew works, modifying chosen options requires a full uninstall followed by a fresh install. Note that if "pkgs" is used, all options will be passed to all packages. Unrecognized options for a package will be silently ignored by brew.

    CLI Example:

        salt '*' pkg.install <package name> tap='<tap>'
        salt '*' pkg.install php54 taps='["josegonzalez/php", "homebrew/dupes"]' options='["--with-fpm"]'

  Multiple Package Installation Options:

  pkgs

    A list of formulas to install. Must be passed as a python list.

    CLI Example:

        salt '*' pkg.install pkgs='["foo","bar"]'

  Returns a dict containing the new package names and versions:

      {'<package>': {'old': '<old-version>',
                     'new': '<new-version>'}}

  CLI Example:

      salt '*' pkg.install 'package package package'

salt.modules.mac_brew_pkg.latest_version(*names, **kwargs)

  Return the latest version of the named package available for upgrade or installation

  Currently chooses stable versions, falling back to devel if that does not exist.

  CLI Example:

      salt '*' pkg.latest_version <package name>
      salt '*' pkg.latest_version <package1> <package2> <package3>

salt.modules.mac_brew_pkg.list_pkgs(versions_as_list=False, **kwargs)

  List the packages currently installed in a dict:

      {'<package_name>': '<version>'}

  CLI Example:

      salt '*' pkg.list_pkgs

salt.modules.mac_brew_pkg.list_upgrades(refresh=True, include_casks=False, **kwargs)

  Check whether or not an upgrade is available for all packages

  CLI Example:

      salt '*' pkg.list_upgrades

salt.modules.mac_brew_pkg.pin(name=None, pkgs=None, sources=None, **kwargs)

  Set package in 'hold' state, meaning it will not be upgraded.

  Added in version 3001.

  name

    The name of the package, e.g., 'tmux'

  CLI Example:

  >     salt '*' pkg.hold <package name>

  pkgs

    A list of packages to hold. Must be passed as a python list.

  CLI Example:

      salt '*' pkg.hold pkgs='["foo", "bar"]'

salt.modules.mac_brew_pkg.refresh_db(**kwargs)

  Update the homebrew package repository.

  CLI Example:

      salt '*' pkg.refresh_db

salt.modules.mac_brew_pkg.remove(name=None, pkgs=None, **kwargs)

  Removes packages with `brew uninstall`.

  name

    The name of the package to be deleted.

  Multiple Package Options:

  pkgs

    A list of packages to delete. Must be passed as a python list. The `name` parameter will be ignored if this option is passed.

  Added in version 0.16.0.

  Returns a dict containing the changes.

  CLI Example:

      salt '*' pkg.remove <package name>
      salt '*' pkg.remove <package1>,<package2>,<package3>
      salt '*' pkg.remove pkgs='["foo", "bar"]'

salt.modules.mac_brew_pkg.unhold(name=None, pkgs=None, sources=None, **kwargs)

  Set package current in 'hold' state to install state, meaning it will be upgraded.

  Added in version 3001.

  name

    > The name of the package, e.g., 'tmux'

    CLI Example:

        salt '*' pkg.unhold <package name>

  pkgs

    A list of packages to unhold. Must be passed as a python list.

  CLI Example:

      salt '*' pkg.unhold pkgs='["foo", "bar"]'

salt.modules.mac_brew_pkg.unpin(name=None, pkgs=None, sources=None, **kwargs)

  Set package current in 'hold' state to install state, meaning it will be upgraded.

  Added in version 3001.

  name

    > The name of the package, e.g., 'tmux'

    CLI Example:

        salt '*' pkg.unhold <package name>

  pkgs

    A list of packages to unhold. Must be passed as a python list.

  CLI Example:

      salt '*' pkg.unhold pkgs='["foo", "bar"]'

salt.modules.mac_brew_pkg.upgrade(refresh=True, **kwargs)

  Upgrade outdated, unpinned brews.

  refresh

    Fetch the newest version of Homebrew and all formulae from GitHub before installing.

  Returns a dictionary containing the changes:

      {'<package>':  {'old': '<old-version>',
                      'new': '<new-version>'}}

  CLI Example:

      salt '*' pkg.upgrade

salt.modules.mac_brew_pkg.upgrade_available(pkg, **kwargs)

  Check whether or not an upgrade is available for a given package

  CLI Example:

      salt '*' pkg.upgrade_available <package name>

salt.modules.mac_brew_pkg.version(*names, **kwargs)

  Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned.

  CLI Example:

      salt '*' pkg.version <package name>
      salt '*' pkg.version <package1> <package2> <package3>