Home

Awesome

Laptop

Build Status

Laptop is a script to set up an OS X computer for web development, and to keep it up to date.

It can be run multiple times on the same machine safely. It installs, upgrades, or skips packages based on what is already installed on the machine.

Requirements

We support:

Older versions may work but aren't regularly tested. Bug reports for older versions are welcome.

Install

Begin by opening the Terminal application on your Mac. The easiest way to open an application in OS X is to search for it via Spotlight. The default keyboard shortcut for invoking Spotlight is command-Space. Once Spotlight is up, just start typing the first few letters of the app you are looking for, and once it appears, press return to launch it.

In your Terminal window, copy and paste the command below, then press return.

bash <(curl -s https://raw.githubusercontent.com/18F/laptop/master/laptop)

The script itself is available in this repo for you to review if you want to see what it does and how it works.

Note that the script will ask you to enter your OS X password at various points. This is the same password that you use to log in to your Mac. If you don't already have it installed, GitHub for Mac will launch automatically at the end of the script so you can set up everything you'll need to push code to GitHub.

Once the script is done, make sure to quit and relaunch Terminal.

More detailed instructions with a video are available in the Wiki.

It is highly recommended to run the script regularly to keep your computer up to date. Once the script has been installed, you'll be able to run it at your convenience by typing laptop and hitting return in your Terminal.

Want to install just git-seekret?

In your terminal window, copy and paste the following line, and press return:

curl -s https://raw.githubusercontent.com/18F/laptop/master/seekrets-install | bash -

Note that the script may ask you to enter your password. This is the same password that you use to log in to your computer.

git-seekret requires git 2.9.1 or higher. Some versions of Ubuntu ship with an older version. To update your git before installing git-seekret:

sudo add-apt-repository ppa:git-core/ppa
sudo apt-get update

git-seekret will install global git hooks into ~/.git-support/hooks. To restore pre-existing git hooks, it is recommended to save pre-existing hooks into a separate directory and to copy those hooks into ~/.git-support/hooks after git-seekret is installed.

Development

Git Seekret

This section covers contributing and developing new rulesets for git-seekrets.

The rules installed by the seekret-install script are located in the seekret-rules directory at the root of this repository. Inside each rule file is a list of rules. The rule file can be considered a tree with the rules as the leaves of the tree.

An example rule file is below:

thing_to_match:
  match: r[egx]{2,}p?
  unmatch:
    - some_prefix\s*r[egx]{2,}p?
    - r[egx]{2,}p?\s*some_suffix

Using the example above, let's break down each stanza:

Feel free to submit an issue/create a pull request in order to submit a new ruleset or to apply a modifification to an existing ruleset.

Testing Git Seekrets

You can test secret rulesets using BATS for automated testing and manually using the installation script.

Let's talk about BATS

Please read the local BATS documentation.

Let's talk about local manual testing

To install the *.rule files located in the repo, just run the installation script locally. This will update your local ~/.git-support/seekret-rules directory with the changes in this repository.

./seekrets-install

You should now be able to run the check within any repository on your machine.

git seekret check -c 0 # check for secrets within commit history

git seekret check -s # check for secrets within staged files

Debugging

Your last Laptop run will be saved to ~/laptop.log. Read through it to see if you can debug the issue yourself. If not, copy and paste the entire log into a new GitHub Issue for us.

Git Seekrets False Positives

Sometimes the git-seekrets rules may indicate a false positive and match things that aren't actually secrets. This can happen if the regular expressions used to match and unmatch are too strict.

Make sure you have the latest rulesets from this repository by running the git-seekrets installation script.

If the ruleset is still triggering a false positive, please open an issue (or a pull request if you know how to fix the regular expression), and include the text that is being treated as a false positive, along with the rules installed on your computer. Please run this command to output your current rules, then copy and paste them into the GitHub issue:

cat ~/.git-support/seekret-rules/*.rule

What it sets up

It should take less than 15 minutes to install (depends on your machine and internet connection).

Customize in ~/.laptop.local and ~/Brewfile.local

Your ~/.laptop.local is run at the end of the mac script. Put your customizations there. If you want to install additional tools or Mac apps with Homebrew, add them to your ~/Brewfile.local. This repo already contains a .laptop.local and Brewfile.local you can use to get started.

# Go to your OS X user's root directory
cd ~

# Download the sample files to your computer
curl --remote-name https://raw.githubusercontent.com/18F/laptop/master/.laptop.local
curl --remote-name https://raw.githubusercontent.com/18F/laptop/master/Brewfile.local

It lets you install the following tools and apps:

Write your customizations such that they can be run safely more than once. See the mac script for examples.

Laptop functions such as fancy_echo and gem_install_or_update can be used in your ~/.laptop.local.

What about background services (Redis, Postgres, MySQL, etc.)?

The script does not automatically install services like databases because you may not need any particular one, or you may need specific versions, not just the latest. For services, we recommend using Docker. For example, you can use the [docker run] command to start a service in a container and make the container's port available to your local machine:

docker run -p 5432 postgres:10.6

You can also use Docker Compose to define your app's containers and their relationships, cutting out the need to manually setup each service.

How to switch your shell back to bash from zsh (or vice versa)

  1. Find out which shell you're currently running: echo $SHELL

  2. Find out the location of the shell you want to switch to. For example, if you want to switch to bash, run which bash.

  3. Verify if the shell location is included in /etc/shells. Run cat /etc/shells to see the contents of the file.

  4. If the location of the shell is included, run chsh -s [the location of the shell]. For example, if which bash returned /bin/bash, you would run chsh -s /bin/bash.

    If the location of the shell is not in /etc/shells, add it, then run the chsh command. If you have Sublime Text, you can open the file by running subl /etc/shells.

  5. Quit and restart Terminal (or iTerm2), or open a new tab for the new shell to take effect.

Whether you're using bash or zsh, we recommend installing the latest versions with Homebrew because the versions that came with your Mac are really old.

brew install bash

or

brew install zsh

Credits

The 18F laptop script is based on and inspired by thoughtbot's laptop script.

Public domain

thoughtbot's original work remains covered under an MIT License.

18F's work on this project is in the worldwide public domain, as are contributions to our project. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.