README.md

   1 # Homebrew Bundle
   2
   3 Bundler for non-Ruby dependencies from Homebrew, Homebrew Cask, Mac App Store, Whalebrew and Visual Studio Code.
   4
   5 ## Requirements
   6
   7 [Homebrew](https://github.com/Homebrew/brew) (on macOS or [Linux](https://docs.brew.sh/Homebrew-on-Linux)) for installing dependencies.
   8
   9 [Homebrew Cask](https://github.com/Homebrew/homebrew-cask) is optional and used for installing Mac applications.
  10
  11 [mas-cli](https://github.com/mas-cli/mas) is optional and used for installing Mac App Store applications.
  12
  13 [Whalebrew](https://github.com/whalebrew/whalebrew) is optional and used for installing Whalebrew images.
  14
  15 [Visual Studio Code](https://code.visualstudio.com/) is optional and used for installing Visual Studio Code extensions.
  16
  17 ## Installation
  18
  19 `brew bundle` is automatically installed when first run.
  20
  21 ## Usage
  22
  23 See [the `brew bundle` section of the `brew generate-man-completions` output](https://docs.brew.sh/Manpage#bundle-subcommand) or `brew bundle --help`.
  24
  25 An example `Brewfile`:
  26
  27 ```ruby
  28 # 'brew tap'
  29 tap "homebrew/cask"
  30 # 'brew tap' with custom Git URL
  31 tap "user/tap-repo", "https://user@bitbucket.org/user/homebrew-tap-repo.git"
  32 # 'brew tap' with arguments
  33 tap "user/tap-repo", "https://user@bitbucket.org/user/homebrew-tap-repo.git", force_auto_update: true
  34
  35 # set arguments for all 'brew install --cask' commands
  36 cask_args appdir: "~/Applications", require_sha: true
  37
  38 # 'brew install'
  39 brew "imagemagick"
  40 # 'brew install --with-rmtp', 'brew services restart' on version changes
  41 brew "denji/nginx/nginx-full", args: ["with-rmtp"], restart_service: :changed
  42 # 'brew install', always 'brew services restart', 'brew link', 'brew unlink mysql' (if it is installed)
  43 brew "mysql@5.6", restart_service: true, link: true, conflicts_with: ["mysql"]
  44 # install only on specified OS
  45 brew "gnupg" if OS.mac?
  46 brew "glibc" if OS.linux?
  47
  48 # 'brew install --cask'
  49 cask "google-chrome"
  50 # 'brew install --cask --appdir=~/my-apps/Applications'
  51 cask "firefox", args: { appdir: "~/my-apps/Applications" }
  52 # bypass Gatekeeper protections (NOT RECOMMENDED)
  53 cask "firefox", args: { no_quarantine: true }
  54 # always upgrade auto-updated or unversioned cask to latest version even if already installed
  55 cask "opera", greedy: true
  56 # 'brew install --cask' only if '/usr/libexec/java_home --failfast' fails
  57 cask "java" unless system "/usr/libexec/java_home", "--failfast"
  58
  59 # 'mas install'
  60 mas "1Password", id: 443_987_910
  61
  62 # 'whalebrew install'
  63 whalebrew "whalebrew/wget"
  64
  65 # 'vscode --install-extension'
  66 vscode "GitHub.codespaces"
  67 ```
  68
  69 ## Versions and lockfiles
  70
  71 Homebrew is a [rolling release](https://en.wikipedia.org/wiki/Rolling_release) package manager so it does not support installing arbitrary older versions of software.
  72 If your software needs specific pinned versions, consider [`whalebrew`](https://github.com/whalebrew/whalebrew) lines in your `Brewfile` to install [Docker](https://www.docker.com) containers.
  73
  74 After a successful `brew bundle` run, it creates a `Brewfile.lock.json` to record the environment. If a future `brew bundle` run fails, you can check the differences between `Brewfile.lock.json` to debug. As it can contain local environment information that varies between systems, it's not worth committing to version control on multi-user repositories.
  75
  76 Disable generation of the `Brewfile.lock.json` file by setting the environment variable with `export HOMEBREW_BUNDLE_NO_LOCK=1` or by using the command-line argument `brew bundle --no-lock`.
  77
  78 ## New Installers/Checkers/Dumpers
  79
  80 `brew bundle` currently supports Homebrew, Homebrew Cask, Mac App Store, Whalebrew and Visual Studio Code.
  81
  82 We are interested in contributions for other installers/checkers/dumpers but they must:
  83
  84 - be able to install software without user interaction
  85 - be able to check if software is installed
  86 - be able to dump the installed software to a format that can be stored in a `Brewfile`
  87 - not require `sudo` to install
  88 - be extremely widely used
  89
  90 Note: based on these criteria, we would not accept e.g. Whalebrew (but have no plans to remove it.)
  91
  92 ## Tests
  93
  94 Tests can be run with `bundle install && bundle exec rspec`.
  95 Syntax linting can be run with `brew style homebrew/bundle`.
  96
  97 ## Copyright
  98
  99 Copyright (c) Homebrew maintainers and Andrew Nesbitt. See [LICENSE](https://github.com/Homebrew/homebrew-bundle/blob/HEAD/LICENSE) for details.