Skip to content

Latest commit

 

History

History
251 lines (175 loc) · 9.13 KB

index.md

File metadata and controls

251 lines (175 loc) · 9.13 KB
Raw

sg - the Sourcegraph developer tool

          _____                    _____
         /\    \                  /\    \
        /::\    \                /::\    \
       /::::\    \              /::::\    \
      /::::::\    \            /::::::\    \
     /:::/\:::\    \          /:::/\:::\    \
    /:::/__\:::\    \        /:::/  \:::\    \
    \:::\   \:::\    \      /:::/    \:::\    \
  ___\:::\   \:::\    \    /:::/    / \:::\    \
 /\   \:::\   \:::\    \  /:::/    /   \:::\ ___\
/::\   \:::\   \:::\____\/:::/____/  ___\:::|    |
\:::\   \:::\   \::/    /\:::\    \ /\  /:::|____|
 \:::\   \:::\   \/____/  \:::\    /::\ \::/    /
  \:::\   \:::\    \       \:::\   \:::\ \/____/
   \:::\   \:::\____\       \:::\   \:::\____\
    \:::\  /:::/    /        \:::\  /:::/    /
     \:::\/:::/    /          \:::\/:::/    /
      \::::::/    /            \::::::/    /
       \::::/    /              \::::/    /
        \::/    /                \::/____/
         \/____/

sg is the CLI tool that Sourcegraph developers can use to develop Sourcegraph. Learn more about the tool's overall vision in sg Vision, and how to use it in the usage section.

NOTE: Have feedback or ideas? Feel free to open a discussion! Sourcegraph teammates can also leave a message in #dev-experience.

Quickstart

  1. Run the following to download and install sg:

    curl --proto '=https' --tlsv1.2 -sSLf https://install.sg.dev | sh

  2. In your clone of sourcegraph/sourcegraph, start the default Sourcegraph environment:

    sg start

  3. Once the enterprise-web process has finished compilation, open https://sourcegraph.test:3443 in your browser.

A more detailed introduction is available in the development quickstart guide.

Installation

Run the following command in a terminal:

curl --proto '=https' --tlsv1.2 -sSLf https://install.sg.dev | sh

That will download the latest release of sg from here, put it in a temporary location and run sg install to install it to a permanent location in your $PATH.

For other installation options, see Advanced installation.

Updates

Once set up, sg will automatically check for updates and update itself if a change is detected in your local copy of origin/main. To force a manual update of sg, run:

sg update

In order to temporarily turn off automatic updates, run your commands with the -skip-auto-update flag or SG_SKIP_AUTO_UPDATE environment variable:

sg -skip-auto-update [cmds ...]

On the next command run, if a new version is detected, sg will auto update before running.

To see what's changed, use sg version changelog.

Usage

Refer to the generated sg reference for complete documentation of all commands.

Help

You can get help about commands locally in a variety of ways:

sg help # show all available commands

# learn about a specific command or subcommand
sg <command> -h
sg <command> --help

A full reference is available in the generated sg reference. You can also view the full reference locally with sg help -full.

Autocompletion

If you have used sg setup, you should have autocompletions set up for sg. To enable it, type out a partial command and press the Tab key twice. For example:

sg start<tab><tab>

To get autocompletions for the available flags for a command, type out a command and - and press the Tab key twice. For example:

sg start -<tab><tab>

Both of the above work if you provide partial values as well to narrow down the suggestions. For example, the following will suggest run sets that start with web-:

sg start web-<tab><tab>

Configuration

Default sg behaviour is configured through the sg.config.yaml file in the root of the sourcegraph/sourcegraph repository. Take a look at that file to see which commands are run in which environment, how these commands set setup, what environment variables they use, and more.

To modify your configuration locally, you can overwrite chunks of configuration by creating a sg.config.overwrite.yaml file in the root of the repository. It's .gitignored so you won't accidentally commit those changes.

If an sg.config.overwrite.yaml file exists, its contents will be merged with the content of sg.config.yaml, overwriting where there are conflicts. This is useful for running custom command sets or adding environment variables specific to your work.

You can run sg run debug-env to see the environment variables passed sg's child processes.

Configuration examples

Changing database configuration

In order to change the default database configuration, the username and the database, for example, create an sg.config.overwrite.yaml file that looks like this:

env:
  PGUSER: 'mrnugget'
  PGDATABASE: 'my-database'

That works for all the other env variables in sg.config.yaml too.

Defining a custom environment by setting a commandset

You can customize what boots up in your development environment by defining a commandSet in your sg.config.overwrite.yaml.

For example, the following defines a commandset called minimal-batches that boots up a minimal environment to work on Batch Changes:

commandsets:
  minimal-batches:
    checks:
      - docker
      - redis
      - postgres
    commands:
      - enterprise-frontend
      - enterprise-worker
      - enterprise-repo-updater
      - enterprise-web
      - gitserver
      - searcher
      - symbols
      - caddy
      - github-proxy
      - zoekt-indexserver-0
      - zoekt-indexserver-1
      - zoekt-webserver-0
      - zoekt-webserver-1
      - batches-executor-firecracker

With that in sg.config.overwrite.yaml you can now run sg start minimal-batches.

Attach a debugger

To attach the Delve debugger, pass the environment variable DELVE=true into sg. Read more here

Offline development

Sometimes you will want to develop Sourcegraph but it just so happens you will be on a plane or a train or perhaps a beach, and you will have no WiFi. And you may raise your fist toward heaven and say something like, "Why, we can put a man on the moon, so why can't we develop high-quality code search without an Internet connection?" But lower your hand back to your keyboard and fret no further, you can develop Sourcegraph with no connectivity by setting the OFFLINE environment variable:

OFFLINE=true sg start

Contributing to sg

Want to hack on sg? Great! Here's how:

  1. Read through the sg Vision to get an idea of what sg should be in the long term.
  2. Explore the sg source code.
  3. Look at the open sg issues.

When you want to hack on sg it's best to be in the dev/sg directory and run it from there:

cd dev/sg
go run . -config ../../sg.config.yaml start

The -config can be anything you want, of course.

Have questions or need help? Feel free to open a discussion! Sourcegraph teammates can also leave a message in #dev-experience.

NOTE: For Sourcegraph teammates, we have a weekly sg hack hour you can hop in to if you're interested in contributing!

Advanced installation

Dockerized sg

A sourcegraph/sg Docker image is available:

# ... 
COPY --from us.gcr.io/sourcegraph-dev/sg:insiders /usr/local/bin/sg ./sg
# ...

Manually building the binary

NOTE: This method requires that Go has already been installed according to the development quickstart guide.

If you want full control over where the sg binary ends up, use this option.

In the root of sourcegraph/sourcegraph, run:

go build -o ~/my/path/sg ./dev/sg

Then make sure that ~/my/path is in your $PATH.

NOTE: For Linux users: A command called sg is already available at /usr/bin/sg. To use the Sourcegraph sg CLI, you need to make sure that its location comes first in PATH. For example, by prepending $GOPATH/bin:

export PATH=$GOPATH/bin:$PATH

Instead of the more conventional:

export PATH=$PATH:$GOPATH/bin

Or you may add an alias to your .bashrc:

alias sg=$HOME/go/bin/sg