-
Notifications
You must be signed in to change notification settings - Fork 233
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document the Sass migrator #372
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -67,6 +67,28 @@ namespace :sass do | |
end | ||
end | ||
|
||
namespace :migrator do | ||
# Check out the latest commit of the Sass migrator into the .sass-migrator directory. | ||
task :checkout do | ||
unless Dir.exists?(".sass-migrator") | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Lint/DeprecatedClassMethods: Dir.exists? is deprecated in favor of Dir.exist?. |
||
sh %{git clone git://github.com/sass/migrator .sass-migrator} | ||
end | ||
|
||
Dir.chdir(".sass-migrator") do | ||
sh %{git fetch} | ||
if ENV["SASS_MIGRATOR_REVISION"] | ||
sh %{git checkout #{ENV["SASS_MIGRATOR_REVISION"]}} | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Style/StringLiteralsInInterpolation: Prefer single-quoted strings inside interpolations. |
||
else | ||
sh %{git checkout origin/master} | ||
end | ||
end | ||
end | ||
|
||
task :version => :checkout do | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Style/HashSyntax: Use the new Ruby 1.9 hash syntax. |
||
add_version 'migrator', Dir.chdir(".sass-migrator") {latest_stable_tag} | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Style/StringLiterals: Prefer double-quoted strings unless you need single quotes to avoid extra backslashes for escaping. |
||
end | ||
end | ||
|
||
namespace :libsass do | ||
# Check out the latest commit of Dart Sass into the .libsass directory. | ||
task :checkout do | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
```shellsession | ||
$ cat style.scss | ||
$body-bg: #000; | ||
$body-color: #111; | ||
|
||
@import "bootstrap"; | ||
|
||
@include media-breakpoint-up(sm) { | ||
.navbar { | ||
display: block; | ||
} | ||
} | ||
$ sass-migrator --migrate-deps module style.scss | ||
$ cat style.scss | ||
@use "bootstrap" with ( | ||
$body-bg: #000, | ||
$body-color: #111 | ||
); | ||
|
||
@include bootstrap.media-breakpoint-up(sm) { | ||
.navbar { | ||
display: block; | ||
} | ||
} | ||
``` |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,292 @@ | ||
--- | ||
title: "Migrator" | ||
table_of_contents: true | ||
introduction: > | ||
TODO(nweiz): Write this | ||
The Sass migrator automatically updates your Sass files to help you move on to | ||
the latest and greatest version of the language. Each of its commands migrates | ||
a single feature, to give you as much control as possible over what you update | ||
and when. | ||
--- | ||
|
||
## Usage | ||
|
||
To use the Sass migrator, tell it [which migration][] you want to run and what | ||
Sass files you want to migrate: | ||
|
||
[which migration]: #migrations | ||
|
||
``` | ||
sass-migrator <migration> <entrypoint.scss...> | ||
``` | ||
|
||
By default, the migrator will only change files that you explicitly pass on the | ||
command line. Passing the [`--migrate-deps` option][] tells the migrator to also | ||
change all the stylesheets that are loaded using the [`@use` rule][], | ||
[`@forward` rule][], or [`@import` rule][]. And if you want to do a test run to | ||
see what changes will be made without actually saving them, you can pass | ||
<code>[--dry-run][] [--verbose][]</code> (or `-nv` for short). | ||
|
||
[`--migrate-deps` option]: #migrate-deps | ||
[`@use` rule]: ../at-rules/use | ||
[`@forward` rule]: ../at-rules/forward | ||
[`@import` rule]: ../at-rules/import | ||
[--dry-run]: #dry-run | ||
[--verbose]: #verbose | ||
|
||
<%= partial 'code-snippets/example-module-migrator' %> | ||
|
||
## Installation | ||
|
||
You can install the Sass migrator from most of the same places that you can | ||
install [Dart Sass](/dart-sass): | ||
|
||
### Standalone | ||
|
||
You can install the Sass migrator on Windows, Mac, or Linux by downloading the | ||
package for your operating system [from GitHub][] and [adding it to your | ||
`PATH`][]. | ||
|
||
[from GitHub]: <%= release_url(:migrator) %> | ||
[adding it to your `PATH`]: https://katiek2.github.io/path-doc/ | ||
|
||
### npm | ||
|
||
If you use Node.js, you can also install the Sass migrator using [npm][] by | ||
running | ||
|
||
[npm]: https://www.npmjs.com | ||
|
||
``` | ||
npm install -g sass-migrator | ||
``` | ||
|
||
### Chocolatey | ||
|
||
If you use [the Chocolatey package manager][] for Windows, you can install the | ||
Sass migrator by running | ||
|
||
[the Chocolatey package manager]: https://chocolatey.org | ||
|
||
``` | ||
choco install sass-migrator | ||
``` | ||
|
||
### Homebrew | ||
|
||
If you use [the Homebrew package manager][] for Mac OS X, you can install Dart | ||
Sass by running | ||
|
||
[the Homebrew package manager]: https://brew.sh | ||
|
||
``` | ||
brew install sass/sass/migrator | ||
``` | ||
|
||
## Global Options | ||
|
||
These options are available for all migrators. | ||
|
||
### `--migrate-deps` | ||
|
||
This option (abbreviated `-d`) tells the migrator to change not just the | ||
stylesheets that are explicitly passed on the command line, but also any | ||
stylesheets that they depend on using the [`@use` rule][], [`@forward` rule][], | ||
or [`@import` rule][]. | ||
|
||
```shellsession | ||
$ sass-migrator module --verbose style.scss | ||
Migrating style.scss | ||
$ sass-migrator module --verbose --migrate-deps style.scss | ||
Migrating style.scss | ||
Migrating _theme.scss | ||
Migrating _fonts.scss | ||
Migrating _grid.scss | ||
``` | ||
|
||
### `--dry-run` | ||
|
||
This flag (abbreviated `-n`) tells the migrator not to save any changes to | ||
disk. It instead prints the list of files that it would have changed. This is | ||
commonly paired with the [`--verbose` option][] to print the contents of the | ||
changes that would have been made as well. | ||
|
||
[`--verbose` option]: #verbose | ||
|
||
```shellsession | ||
$ sass-migrator module --dry-run --migrate-deps style.scss | ||
Dry run. Logging migrated files instead of overwriting... | ||
|
||
style.scss | ||
_theme.scss | ||
_fonts.scss | ||
_grid.scss | ||
``` | ||
|
||
#### `--no-unicode` | ||
|
||
This flag tells the Sass migrator only to emit ASCII characters to the terminal | ||
as part of error messages. By default, or if `--unicode` is passed, the migrator | ||
will emit non-ASCII characters for these messages. This flag does not affect the | ||
CSS output. | ||
|
||
```shellsession | ||
$ sass-migrator --no-unicode module style.scss | ||
line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'. | ||
, | ||
1 | @import "typography"; | ||
| ^^^^^^^^^^^^ | ||
' | ||
Migration failed! | ||
$ sass-migrator --unicode module style.scss | ||
line 1, column 9 of style.scss: Error: Could not find Sass file at 'typography'. | ||
╷ | ||
1 │ @import "typography"; | ||
│ ^^^^^^^^^^^^ | ||
╵ | ||
Migration failed! | ||
``` | ||
|
||
### `--verbose` | ||
|
||
This flag (abbreviated `-v`) tells the migrator to print extra information to | ||
the console. By default, it just prints the name of files that are changed, but | ||
when combined with the [`--dry-run` option][] it also prints those files' new | ||
contents. | ||
|
||
[`--dry-run` option]: #dry-run | ||
|
||
<%# Indent this because otherwise the table-of-contents generator interprets | ||
the `===` as a heading. %> | ||
|
||
$ sass-migrator module --verbose --dry-run style.scss | ||
Dry run. Logging migrated files instead of overwriting... | ||
|
||
style.scss | ||
================================================================================ | ||
@use "bootstrap" with ( | ||
$body-bg: #000, | ||
$body-color: #111 | ||
); | ||
|
||
@include bootstrap.media-breakpoint-up(sm) { | ||
.navbar { | ||
display: block; | ||
} | ||
} | ||
|
||
-------------------------------------------------------------------------------- | ||
$ sass-migrator module --verbose style.scss | ||
Migrating style.scss | ||
|
||
## Migrations | ||
|
||
The migrator currently supports only one migration, but expect more to come as | ||
the Sass language continues to evolve! | ||
|
||
### Module | ||
|
||
This migration converts stylesheets that use the old [`@import` rule][] to load | ||
dependencies so that they use the Sass module system via the [`@use` rule][] | ||
instead. It doesn't just naïvely change `@import`s to `@use`s—it updates | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Consider splitting this up: This migration updates stylesheets that load dependencies to use the Sass module system. Any usages of the old [ There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'd like to keep this as-is, because I feel like the existing wording makes it clearer that you can run the migrator on stylesheets that mix |
||
stylesheets intelligently so that they keep working the same way they did | ||
before, including: | ||
|
||
* Adding namespaces to uses of members (variables, mixins, and functions) from | ||
other modules. | ||
|
||
* Adding new `@use` rules to stylesheets that were using members without | ||
importing them. | ||
|
||
* Converting overridden default variables to [`with` clauses][]. | ||
|
||
[`with` clauses]: ../at-rules/use#configuring-modules | ||
|
||
* Automatically removing `-` and `_` prefixes from members that are used from | ||
other files (because otherwise they'd be considered [private][] and could only | ||
be used in the module they're declared). | ||
|
||
[private]: ../at-rules/use#private-members | ||
|
||
* Converting [nested imports][] to use the [`meta.load-css()` mixin][] instead. | ||
|
||
[nested imports]: ../at-rules/import#nesting | ||
[`meta.load-css()` mixin]: ../modules/meta#load-css | ||
|
||
<% heads_up do %> | ||
Because the module migrator may need to modify both member definitions *and* | ||
member names, it's important to either run it with the [`--migrate-deps` | ||
option][] or ensure that you pass it all the stylesheets in your package or | ||
application. | ||
|
||
[`--migrate-deps` option]: #migrate-deps | ||
<% end %> | ||
|
||
<%= partial 'code-snippets/example-module-migrator' %> | ||
|
||
#### `--remove-prefix` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It would be good to mention here that passing this option will also generate an import-only stylesheet that forwards the entrypoint with the prefixes still intact, and that this option is unnecessary when migrating downstream stylesheets whose dependencies have already been migrated following this pattern. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done. |
||
|
||
This option (abbreviated `-p`) takes an identifier prefix to remove from the | ||
beginning of all variable, mixin, and function names when they're migrated. | ||
Members that don't start with this prefix will remain unchanged. | ||
|
||
The [`@import` rule][] put all top-level members in one global scope, so when it | ||
was the standard way of loading stylesheets, everyone was incentivized to add | ||
prefixes to all their member names to avoid accidentally redefining some other | ||
stylesheet's. The module system solves this problem, so it's useful to | ||
automatically strip those old prefixes now that they're unnecessary. | ||
|
||
```shellsession | ||
$ cat style.scss | ||
@import "theme"; | ||
|
||
@mixin app-inverted { | ||
color: $app-bg-color; | ||
background-color: $app-color; | ||
} | ||
$ sass-migrator --migrate-deps module --remove-prefix=app- style.scss | ||
$ cat style.scss | ||
@import "theme"; | ||
|
||
@mixin inverted { | ||
color: theme.$bg-color; | ||
background-color: theme.$color; | ||
} | ||
``` | ||
|
||
#### `--forward` | ||
|
||
This option tells the migrator which members to forward using the [`@forward` | ||
rule][]. It supports the following settings: | ||
|
||
* `none` (the default) doesn't forward any members. | ||
|
||
* `all` forwards all members except those that started with `-` or `_` in the | ||
original stylesheet, since that was commonly used to mark a package-private | ||
member before the module system was introduced. | ||
|
||
* `prefixed` forwards only members that begin with the prefix passed to the | ||
[`--remove-prefix` option][]. This option may only be used in conjunction with | ||
the `--remove-prefix` option. | ||
|
||
[`--remove-prefix` option]: #remove-prefix | ||
|
||
All files that are passed explicitly on the command line will forward members | ||
that are transitively loaded by those files using the `@import` rule. Files | ||
loaded using the [`--migrate-deps` option][] will not forward any new members. | ||
This option is particularly useful when migrating a Sass library, because it | ||
ensures that users of that library will still be able to access all the members | ||
it defines. | ||
|
||
```shellsession | ||
$ cat _index.scss | ||
@import "theme"; | ||
@import "typography"; | ||
@import "components"; | ||
$ sass-migrator --migrate-deps module --forward=all style.scss | ||
$ cat _index.scss | ||
@forward "theme"; | ||
@forward "typography"; | ||
@forward "components/button"; | ||
@forward "components/nav"; | ||
@forward "components/drawer"; | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Metrics/LineLength: Line is too long. [89/80]