Skip to content

Command Line Tool

Jump to bottom Edit New page
chriseppstein edited this page Sep 13, 2010 · 12 revisions

The compass command line tool is used to setup and compile your project’s sass files.

Usage Examples

Setting up a new project

Generate a simple project using the compass defaults and no framework:

compass my_project

Generate a blueprint project using the compass defaults:

compass -f blueprint my_project

Generate a project with a specific directory structure (a.k.a. install into an existing project):

compass --sass-dir=src/sass --css-dir=assets/stylesheets --javascript-dir=assets/javascripts --images-dir=assets/images my_project

Generate a project using a plugin:

compass -r plugin_library -f framework_name my_project

Install into a rails application:

compass -f blueprint --rails my_project

Install into the current directory:

compass -f blueprint -i

Compiling your project

Watch a project for changes:

$ cd my_project
$ compass -w

Watch a project when you’re not in the project directory

$ compass -w my_project

Recompile only out-of-date css:

$ cd my_project
$ compass

Recompile from another directory:

$ compass -u my_project

Recompile all files:

$ compass --force

Compile your stylesheets for production

Option A: Use the compass production defaults

compass -e production --force

Option B: Override your configuration defaults on the command line

compass -s compressed --force

Option C: Create a separate configuration file for production

$ cp config.rb prod_config.rb
$ ..edit prod_config.rb to suit  your needs..
$ compass -c prod_config.rb --force

Working with Patterns

Stamp a pattern:

$ cd my_project
$ compass -f blueprint -p link_icons
   exists my_project
directory images/link_icons/
   exists src
   exists stylesheets
   create src/link_icons.sass
   create images/link_icons/doc.png
   create images/link_icons/email.png
   create images/link_icons/external.png
   create images/link_icons/feed.png
   create images/link_icons/im.png
   create images/link_icons/pdf.png
   create images/link_icons/visited.png
   create images/link_icons/xls.png
   exists stylesheets
unchanged src/ie.sass
  compile src/link_icons.sass
   create stylesheets/link_icons.css
unchanged src/print.sass
unchanged src/screen.sass

To import your new stylesheets add the following lines of HTML (or equivalent) to your webpage:

<head>
  <link href="/stylesheets/link_icons.css" media="screen, projection" rel="stylesheet" type="text/css" />
</head>

How to set up a project with no generated files.

$ mkdir my_project
$ cd my_project
$ compass --write-configuration --css-dir stylesheets --sass-dir sass
   create config.rb
$ mkdir sass
... create sass files in the sass directory (E.g. application.sass) ...
$ compass
directory stylesheets/
  compile sass/application.sass
   create stylesheets/application.css

Full Usage Output

$ compass -h
Usage: compass [options] [project]

Description:
  The compass command line tool will help you create and manage the stylesheets for your
  project.

  To get started on a stand-alone project based on blueprint:

    compass -f blueprint my_compass_project

  When you change any sass files, you must recompile your project
  using --update or --watch.

Mode Options(only specify one):
    -i, --install                    Create a new compass project.
                                       The default mode when a project is provided.
    -u, --update                     Update the current project.
                                       This is the default when no project is provided.
    -w, --watch                      Monitor the current project for changes and update
    -p, --pattern PATTERN            Stamp out a pattern into the current project.
                                       Must be used with -f.
        --write-configuration        Write the current configuration to the configuration
                                       file.
        --list-frameworks            List compass frameworks available to use.
        --validate                   Validate your project's compiled css. Requires Java.
        --grid-img [DIMENSIONS]      Generate a background image to test grid alignment.
                                       Dimension is given as <column_width>+<gutter_width>.
                                       Defaults to 30+10.

Install/Pattern Options:
    -f, --framework FRAMEWORK        Use the specified framework. Only one may be
                                       specified.
    -n, --pattern-name NAME          The name to use when stamping a pattern.
                                       Must be used in combination with -p.
        --rails                      Sets the project type to a rails project.

Configuration Options:
    -c, --config CONFIG_FILE         Specify the location of the configuration file
                                       explicitly.
        --sass-dir SRC_DIR           The source directory where you keep your sass
                                       stylesheets.
        --css-dir CSS_DIR            The target directory where you keep your css
                                       stylesheets.
        --images-dir IMAGES_DIR      The directory where you keep your images.
        --javascripts-dir JS_DIR     The directory where you keep your javascripts.
    -e, --environment ENV            Use sensible defaults for your current environment.
                                       One of: development, production (default)
    -s, --output-style STYLE         Select a CSS output mode.
                                       One of: nested, expanded, compact, compressed
        --relative-assets            Make compass asset helpers generate relative urls to
                                       assets.

General Options:
    -r, --require LIBRARY            Require the given ruby LIBRARY before running
                                       commands. This is used to access compass plugins
                                       without having a project configuration file.
    -q, --quiet                      Quiet mode.
        --dry-run                    Dry Run. Tells you what it plans to do.
        --trace                      Show a full stacktrace on error
        --force                      Force. Allows some failing commands to succeed
                                       instead.
        --imports                    Emit imports suitable for passing to the sass
                                       command-line. Example:
                                       sass `compass --imports`
                                       Note: Compass's Sass extensions will not be
                                       available.
        --install-dir                Emit the location where compass is installed.
    -?, -h, --help                   Show this message
    -v, --version                    Print version
Add a custom footer
Add a custom sidebar

Clone this wiki locally