:toc: macro
:toclevels: 5
:figure-caption!:

= Sublime Text Kit

[link=http://badge.fury.io/rb/sublime_text_kit]
image::https://badge.fury.io/rb/sublime_text_kit.svg[Gem Version]
[link=https://www.alchemists.io/projects/code_quality]
image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide]
[link=https://circleci.com/gh/bkuhlmann/sublime_text_kit]
image::https://circleci.com/gh/bkuhlmann/sublime_text_kit.svg?style=svg[Circle CI Status]

Sublime Text Kit is a command line interface for managing Sublime Text metadata for multiple
projects, sessions, etc. It's also great for generating the metadata you need, while avoiding manual
labor, from existing projects.

toc::[]

== Features

* Provides project metadata (i.e. `.sublime-project` and `.sublime-workspace` files) management for
  project switching via the `CONTROL+COMMAND+P` shortcut.
* Rebuilds project history (Project -> Recent Projects) from existing project files (assumes project
  metadata is in a directory) so one can easily toggle between up-to-date project information via
  the `CONTROL+COMMAND+P` shortcut.

== Requirements

. link:https://www.ruby-lang.org[Ruby]
. link:https://www.sublimetext.com[Sublime Text]

== Setup

To install, run:

[source,bash]
----
gem install sublime_text_kit
----

== Usage

=== Command Line Interface (CLI)

From the command line, type: `sublime_text_kit`

....
USAGE:
  -c, --config ACTION                      Manage gem configuration. Actions: edit or view.
  -h, --help                               Show this message.
  -m, --metadata ACTION                    Manage metadata. Actions: create, delete, or recreate.
  -S, --session                            Rebuild session.
  -s, --snippets [FORMAT]                  View snippets. Default: markdown. Formats: markdown or ascii_doc.
  -u, --update                             Update metadata and session based on current settings.
  -v, --version                            Show gem version.
....

=== Customization

This gem can be configured via a global configuration:
`~/.config/sublime_text_kit/configuration.yml`. It can also be configured via
link:https://www.alchemists.io/projects/xdg[XDG] environment variables.

An example configuration could be:

[source,yaml]
----
:project_roots:
  - "~/Engineering/Contributions"
  - "~/Engineering/OSS"
:metadata_dir: "~/Dropbox/Cache/Sublime"
:snippets_format: :ascii_doc
----

Feel free to take this configuration, modify, and save as your own custom `+configuration.yml+`.

The project roots define the root level directories where project folders are located. When project
metadata (i.e. `.sublime-project`, `.sublime-workspace`) is generated, the name of the metadata file
will be the same name as that of the project folder. All project metadata, regardless of root
location, is written to the same metadata directory. If using the example settings shown above and
assuming the following directory structure exists…

....
~/Engineering/OSS/example
~/Engineering/OSS/sublime_text_kit
....

…the project metadata will be created in the workspace directory as follows:

....
~/Dropbox/Cache/Sublime/example.sublime-project
~/Dropbox/Cache/Sublime/example.sublime-workspace
~/Dropbox/Cache/Sublime/sublime_text_kit.sublime-project
~/Dropbox/Cache/Sublime/sublime_text_kit.sublime-workspace
....

=== Workflow

The following demonstrates a default Sublime Text setup:

. Run: `sublime_text_kit --config --edit` (define Sublime Text Kit settings for project roots and
  metadata directory).
. Shutdown Sublime Text (i.e. `CONTROL+Q`).
. Run: `sublime_text_kit --metadata create` (creates project metadata and rebuilds the session
  metadata so Sublime Text has a complete project history from which to jump through via the
  `CONTROL+COMMMAND+P` shortcut).
. Launch Sublime Text and use the `CONTROL+COMMAND+P` keyboard shortcut to toggle between
  projects. Notice that you can (fuzzy type) project names to jump between them.
. Breeze through your project workload with ease. 🎉

=== Troubleshooting

* When rebuilding workspaces, ensure Sublime Text is shutdown or changes won’t be applied.
* When rebuilding workspaces, ensure workspace_dir (as defined via settings.yml) points to a
  directory containing `.sublime-project` and `.sublime-workspace` files.

== Development

To contribute, run:

[source,bash]
----
git clone https://github.com/bkuhlmann/sublime_text_kit.git
cd sublime_text_kit
bin/setup
----

You can also use the IRB console for direct access to all objects:

[source,bash]
----
bin/console
----

== Tests

To test, run:

[source,bash]
----
bundle exec rake
----

== Versioning

Read link:https://semver.org[Semantic Versioning] for details. Briefly, it means:

* Major (X.y.z) - Incremented for any backwards incompatible public API changes.
* Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
* Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.

== Code of Conduct

Please note that this project is released with a link:CODE_OF_CONDUCT.adoc[CODE OF CONDUCT]. By
participating in this project you agree to abide by its terms.

== Contributions

Read link:CONTRIBUTING.adoc[CONTRIBUTING] for details.

== License

Read link:LICENSE.adoc[LICENSE] for details.

== History

Read link:CHANGES.adoc[CHANGES] for details.

== Credits

Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].