Sublime Gitlab Integrate
========================
This is a Sublime Text 2/3 Plugin that integrates various Gitlab features (primarily dealing with issue management, currently) into the editor. 

Installation
----------
There are 3 ways to install:

- With Package Control installed:
  1. (*Recommended*) Simply search for "Gitlab Integrate" in the "Install Package" menu and select it

- Without Package Control:
  1. Clone this repository into `[your Sumblime installation directory]/Packages/` 
  2. Clone/download this repo wherever you'd like, then copy the files in it to `[your Sublime installation directory]/Packages/GitlabIntegrate`

Once installed, the plugin can be activated with `cmd+shift+x` (Mac) or `ctrl+shift+x` (Win/Linux).

Configuration
----------
Before using GitlabIntegrate, you should configure the User Settings file. If you do not, the introduction document will appear and prompt you to do so. User settings can be found 3 ways (you may need to create the file if it doesn't exist):

1. Via the menu at 

   `Preferences -> Package Settings -> Gitlab Integrate -> Settings - User`

2. Via the menu at

   `Tools -> Gitlab Integrate -> Access User Settings`
   
3. Via file browser at

   `[sublime installation directory]/Packages/User/GitlabIntegrate.sublime-settings` 

Then, copy and paste the following text into the file (replacing any text already there). Be sure to edit the project_host and user_token fields:

```javascript
{
	//The project host
	"project_host":"",

	//Your user token for GitLab, found in [host]/profile/account 
	"user_token":"",	

	//Displays the new installation window
	"display_intro":false,

	//The name of the tab when using Edit Issue In Tab (note: if you open another tab with this name, weird things might happen)
	"edit_issue_in_tab_name": "[GLI]: Editing Issue",

	//Suppresses output of closed issues for the Select Issue command
	"hide_closed_issues":false,

	//Appears before all GitlabIntegrate outputs in the console and status bar
	"output_prefix":"[GLI]:",

	/*
	The default project ID.
	This can be found by running GitlabIntegrate's "Get Project IDs" command after configuring 
	your host and user_token. All the projects you have access to should be listed with their IDs.
	*/
	"project_id": 0	

	//set to false if you want to use HTTPS with a self-signed certificate
	"verify_ssl":true
}
```

Usage
------
GitlabIntegrate functions can be accessed via the menu (`Tools -> GitlabIntegrate`), with a keyboard shortcut (`Ctrl+Shift+X` on Windows/Linux, `Cmd+Shift+X` on Mac), or via the Command Palette (default: `Cmd+Shift+P` on Mac, `Ctrl+Shift+P` on Windows/Linux). All GLI commands in the command palette begin with "GLI:".

**Edit Issue In Tab**: This mode opens the selected issue for editing in a separate view. To save your changes, simply close the tab.  

**Command Arguments**: When entering a command through the status/input bar, arguments must be comma-separated. All potential arguments are listed to the left of the input box within parentheses. Arguments in square brackets ([]) are optional. 

**Optional and Keyword Arguments**: Optional arguments may be specified as keyword arguments by prepending the argument value with its name and an unescaped equals sign (E.g., to create a new issue called "test_issue" and assign it to the user "robert" without specifying a description, you would type `test_issue, assign_to=username` into the `Create Issue` input box). If no keywords are specified, the arguments are processed left to right. 
With the exception of labels, every argument is represented by its keyword in the prompt.

**Special Notes on Arguments**:

- *Labels*: 

  - The keyword for labels is `labels`

  - If specifying more than one label, you must quote the whole list (e.g., for the `Add Label(s) to Issue` command for the issue #10 you would type: `10, "first_label, second_label"` or `10, labels="first_label, second_label"`)

  - If you only specify one label, it does not matter whether you quote it or not.

  - Specifying labels in the `Edit Issue` command will _replace all current labels_. Explicitly specifying no labels (e.g. `labels=,` or `labels="",`) will remove all labels from the issue.

- *Assign_to*: Users may be idenified by username or user_id (if you happen to know their id). GLI will automatically detect which method you've used.

- *Escaped Characters*: commas (`,`), equals signs (`=`), and double quotes (`"`) in titles/descriptions must be escaped with a backslash (`\`). Only double quotes must be escaped in the `Edit Issue In View` mode.

Modifying
---------
Before modifying GitlabIntegrate, users are encouraged to read [notes_for_modifying.md](./notes_for_modifying.md).