sublime-build: nstructions for overriding default install target

The existing documentation did not include information
covering a common use-case for Go devs - to always install
a specific package, regardless of the current file being

Added a section to docs/ showing users
how to use the flag-override functionality in their
project-specific settings to achieve this.

Change-Id: I6c59e829b8f355101f8b4eab5dc4269daf5f77b2
Reviewed-by: Will Bond <>
Reviewed-by: Jason Buberel <>
diff --git a/docs/ b/docs/
index ea2968c..ab5ed93 100644
--- a/docs/
+++ b/docs/
@@ -15,6 +15,7 @@
  - [Command Flags](#command-flags)
    - [Formatting Command Flag Settings](#formatting-command-flag-settings)
    - [Command Flag Setting Locations](#command-flag-setting-locations)
+   - [Using Command Flags to Specify Build and Install Targets](#using-command-flags-to-specify-build-and-install-targets)
 ## Environment Autodetection
@@ -255,3 +256,66 @@
 Do note that settings do not combine from the global Sublime Text settings and
 project settings. Instead, any settings in a more specific location will
 override those in a less specific location.
+### Using Command Flags to Specify Build and Install Targets
+The default behavior of the build commands is to execute the `go` tool in the
+directory containing the file currently being edited. This behavior is
+consistent with other Sublime Text build systems and is what users typically
+With Go projects, you may want to override this default for commands such as
+`go install`. Consider a project containing a single executable command
+(defined by a Go package containing a main function) in the directory:
+The project contains a large set of library packages that are used by the
+`mycommand` program. These libraries are located in:
+Running `go install` from within these two directories will result in the
+creation of the `.a` files in the `$GOPATH/pkg` directory.
+However, it may be more desirable to always have `go install` compile and
+install the `mycommand` program into your `$GOPATH/bin` directory, regardless
+of the location of the source file you are currently editing.
+To achieve this, you can use the flag override mechanism in your project
+configuration file:
+    "folders":
+    [
+        {
+            "path": "/Users/jbuberel/workspace/src"
+        }
+    ],
+    "settings": {
+        "golang": {
+            "install:flags": ["-v", ""]
+        }
+    }
+This configuration will cause the following command to be used when running the
+`Go: Install` build command:
+> Environment:
+>   GOPATH=/Users/jbuberel/workspace-shared:/Users/jbuberel/workspace
+> Directory: /Users/jbuberel
+> Command: /Users/jbuberel/go15/bin/go install -v
+> Output:
+> Elapsed: 0.955s
+> Result: Success