search

bgreenlee / sublime-github

Sublime Text 2/3 plugin that provides a number of useful commands for GitHub.
MIT License
455 stars 98 forks source link

readme

Sublime GitHub

This is a plugin for the Sublime Text text editor (both versions 2 and 3) that provides a number of useful commands for GitHub, including creating and browsing gists, opening and editing files on GitHub, and bringing up the blame and commit history views.

Installation

You can install via Sublime Package Control plugin. Just open "Package Control: Install Package" in your Command Palette and search for "sublime-github". The plugin should be picked up automatically. If not, restart Sublime Text.

Usage

The first time you run one of the commands, it will ask you for your GitHub username and password in order to create a GitHub API access token, which gets saved in the Sublime GitHub user settings file. Your username and password are not stored anywhere, but if you would rather generate the access token yourself, see the "Generating Your Own Access Token" section below.

The following commands are available in the Command Palette:

The following commands require the Git plugin, available through the Package Manager. After installing, restart Sublime Text.

Note: These commands use the currently checked out branch to generate GitHub URLs. Each command also has a corresponding version, such as GitHub: Blame (default branch), that always uses the default branch configured in plugin settings, regardless of which branch is checked out locally. This default branch is set to main, and can be changed by editing the default_branch setting in Preferences > Package Settings > GitHub. All commands except GitHub: Edit have a corresponding "permalink" version too, like GitHub: Blame (permalink), that uses the most recent commit on the current branch (more info).

Adding Additional Accounts

If have multiple GitHub accounts, or have a private GitHub installation, you can add the other accounts and switch between them whenever you like.

Go to the GitHub user settings file (Preferences -> Package Settings -> GitHub -> Settings - User), and add another entry to the accounts dictionary. If it is another GitHub account, copy the base_uri for the default GitHub entry (if you don't see it, you can get it from Preferences -> Package Settings -> GitHub -> Settings - Default, or in the example below), and just give the account a different name. If you're adding a private GitHub installation, the base_uri will be whatever the base url is for your private GitHub, plus "/api/v3". For example:

"accounts":
{
    "GitHub":
    {
        "base_uri": "https://api.github.com",
        "github_token": "..."
    },
    "YourCo":
    {
        "base_uri": "https://github.yourco.com/api/v3",
        "github_token": ""
    }
}

Don't worry about setting the github_token--that will be set for you automatically, after you switch accounts (Shift-Cmd-P, "GitHub: Switch Accounts").

Key Bindings

You can add your own keyboard shortcuts in Preferences -> Key Bindings - User. For example:

[
    { "keys": ["ctrl+super+g", "ctrl+super+n"], "command": "public_gist_from_selection" },
    { "keys": ["ctrl+super+g", "ctrl+super+p","super+n"], "command": "private_gist_from_selection" },
    { "keys": ["ctrl+super+g", "ctrl+super+o"], "command": "open_gist_in_editor" },
    { "keys": ["ctrl+super+g", "ctrl+super+c"], "command": "open_gist_url" }
]

(Note that ctrl+super+g (^⌘G) conflicts with Sublime Text's Quick Find All, so adjust accordingly.) Available commands can be seen in https://github.com/bgreenlee/sublime-github/blob/master/Github.sublime-commands.

Issues

Generating Your Own Access Token

If you feel uncomfortable giving your GitHub username and password to the plugin, you can generate a GitHub API access token yourself. Just open up a Terminal window/shell (on OS X, Linux or Cygwin), and run:

curl -u username -d '{"scopes":["gist"], "note": "sublime-github"}' https://api.github.com/authorizations

where username is your GitHub username. You'll be prompt for your password first. Then you'll get back a response that includes a 40-digit "token" value (e.g. 6423ba8429a152ff4a7279d1e8f4674029d3ef87). Go to Sublime Text 2 -> Preferences -> Package Settings -> GitHub -> Settings - User, and insert the token there. It should look like:

{
    "github_token": "6423ba8429a152ff4a7279d1e8f4674029d3ef87"
}

Restart Sublime.

That's it!

Configuring a proxy

If you are behind a proxy you can configure it for each account.

Note that until a bug in urllib3 is fixed, in order to use a proxy you also have to force curl mode (curl is required obviously).

For example:

"accounts":
{
    "GitHub":
    {
        "base_uri": "https://api.github.com",
        "https_proxy": "...",
        "force_curl": true
    }
}

Bugs and Feature Requests

http://github.com/bgreenlee/sublime-github/issues

Copyright

Copyright © 2011+ Brad Greenlee. See LICENSE for details.