One command is all you need to update local repositories and their submodules. If a project is using CocoaPods or Composer to manage its dependencies, Pug will automatically update those, too.

Contents

1. Installation
2. Basics
3. Update
4. Configuration
5. Tips
6. Help

Installation

Homebrew

Installing Fig with Homebrew is a snap:

$ brew tap ashur/pug
$ brew install pug

That's it! Installing future updates is also a cinch:

$ brew upgrade pug

Git

You can also install Pug using Git. First, clone this repository:

$ cd ~/tools
$ git clone --recursive https://github.com/ashur/pug.git

🎉 New in v0.7

Next, run the install command and include a directory that's already on your $PATH:

$ pug/bin/pug install /usr/local/bin
Linked to '/usr/local/bin/pug'

This will symlink the pug executable, letting you run pug from anywhere on the command line:

$ cd ~/Desktop/
$ pug --version
pug version 0.7.0

Requirements

Pug requires PHP 5.4 or greater

Upgrading

🎉 New in v0.5

If you're upgrading from v0.5 or later, use the built-in command to fetch the latest version:

$ pug upgrade

If you're upgrading from v0.4 or earlier, the best way to handle all the submodules and fiddly bits is with Pug itself:

$ cd ~/tools/pug
$ pug up

💡 Tip — Not sure which version you're running?

$ pug --version
pug version 0.7.0

Nice. 😁

Basics

After you've installed Pug, try updating a local Git repository at any path:

$ pug update ~/Developer/tapas
Updating '/Users/ashur/Developer/tapas'...

 • Pulling...
   > Already up-to-date.

 • Updating submodules... done.

By default, pug update performs two operations on the repository:

• git pull
• git submodule update

🔬 Learn more about the specifics of what Pug does during an update. You can re-configure the default behavior on a global or per-repository basis. See Configuration for more information.

Using Pug to update repositories at an arbitrary path is nice, but projects make things even easier.

Projects

First, let's add a repository to our list of tracked projects:

$ pug add plank ~/Developer/plank
* plank

Now we can grab updates using the project name instead of the full path:

$ pug update plank

That's nicer! Let's add a few more projects:

$ pug show
* plank
* prompt
* transmit

With a single command, we can update multiple projects and their submodules.

$ pug update all

Enable/Disable

Need to focus on a subset of your projects for a while? Disable anything you don't need:

$ pug disable prompt
* plank
  prompt
* transmit

Pug will hold on to the project definition, but skip it when you update all:

$ pug update all
Updating 'plank'...

 • Pulling...
   > Already up-to-date.

Updating 'transmit'...

 • Pulling...
   > Already up-to-date.

   • Updating submodules... done.

Groups

🎉 New in v0.6

As the list of tracked projects grows, it can get harder to stay organized:

$ pug show
* ansible
* cios
* dotfiles
* mlib
  plank
  prompt
* tapas
* tios
* transmit
* zoo

Groups help keep things nice and tidy. To add a new project to a group, use the <group>/<project> naming pattern:

$ pug add mac/coda ~/Developer/Coda

To move an existing project into a group, just rename it:

$ pug rename ansible sysops/ansible

Much better:

$ pug show
* bots/mlib
* bots/zoo
* dotfiles
* ios/coda
  ios/prompt
* ios/transmit
* mac/coda
* mac/transmit
* sysops/ansible
  web/plank
* web/tapas

In addition to keeping projects organized, we can also perform operations on groups just like individual projects. Done with ios for a while? Disable all the projects in that group:

$ pug disable ios

Want to update just the projects in your bots group? Simple!

$ pug update bots

💡 Tip — Add --all to update disabled projects in the group as well

Update

It's important for you to know what Pug is doing on your behalf during pug update. In order of operations:

git pull
git submodule update --init --recursive

If the pug.update.rebase configuration option is set to true, Pug will instead run:

git fetch
git rebase
git submodule update --init --recursive

🔬 Learn more about how to configure pug update to suit your needs

Dependency Managers

If Pug detects CocoaPods, it will try to determine if an update is necessary. If so:

pod install

If Pug detects Composer and determines an update is necessary:

composer update

To force dependency updates:

$ pug update <target> --force

Submodule State Restoration

🎉 New in v0.5

In previous versions, submodules were always left checked out on a detached HEAD after pug update. If you were doing development on a submodule, checking the submodule back out to its original branch and pulling down changes manually was a hassle.

With state restoration, if a submodule is checked out to a branch, Pug now returns it to its previous state and automatically pulls down any changes from the submodule's remote as well:

$ pug update tapas                     
Updating 'tapas'...

 • Pulling...
   > From github.com:ashur/corpora
   >    7b4a17c..e1caf08  master     -> origin/master
   > Updating 339cea5..57c314f
   > Fast-forward
   >  corpora | 2 +-
   >  1 file changed, 1 insertion(+), 1 deletion(-)

 • Updating submodules...
   > Submodule path 'corpora': checked out 'e1caf08eac44a149b14e4f2bbc4eb12ba6a4e6e4'
   % Submodule path 'corpora': checked out 'master'
   % Submodule path 'corpora': pulling 'master'... done.

Note — If a submodule is checked out on a detached HEAD prior to the update, pug update leaves it that way.

Configuration

Pug supports a few configuration options by piggybacking Git's own config command. They can be set either globally (using the --global flag) or on a per-project basis.

For example, we can change the global pug update behavior to always automatically stash changes:

$ git config --global pug.update.stash true

and still keep the default no-stash behavior where we need to:

$ cd ~/Developer/tapas
$ git config pug.update.stash false

Options

⚙ pug.update.rebase

boolean — When true, pug update will perform git fetch and git rebase instead of git pull.

Default value is false

🎉 New in v0.5

⚙ pug.update.stash

boolean — When true, automatically stash any changes in the active project before pull-ing, then pop the stack afterward

Default value is false

⚙ pug.update.submodules

boolean — Whether to update submodules during pug update

Default value is true

💡 Tips

Save the "date"

Save yourself a few keystrokes every update:

$ pug up

Help

Command-specific help is always available on the command line:

$ pug help
usage: pug [--version] <command> [<args>]

Commands are:
   add        Start tracking a new project
   disable    Exclude projects from 'all' updates
   enable     Include projects in 'all' updates
   install    Symlink 'pug' to a convenient path
   rename     Rename an existing project
   rm         Stop tracking projects
   show       Show tracked projects
   update     Fetch project updates
   upgrade    Fetch the newest version of Pug

See 'pug help <command>' to read about a specific command