= ghq(1) image:https://travis-ci.org/motemen/ghq.svg?branch=master["Build Status", link="https://travis-ci.org/motemen/ghq"]

== NAME

ghq - Manage remote repository clones

== DESCRIPTION

'ghq' provides a way to organize remote repository clones, like +go get+ does. When you clone a remote repository by +ghq get+, ghq makes a directory under a specific root directory (by default +~/.ghq+) using the remote repository URL's host and path.

    $ ghq get https://github.com/motemen/ghq
    # Runs `git clone https://github.com/motemen/ghq ~/.ghq/github.com/motemen/ghq`

You can also list local repositories (+ghq list+), jump into local repositories (+ghq look+), and bulk cloning repositories from several web services (+ghq import+).

== SYNOPSIS

[verse]
'ghq' get [-u] <repository URL> | <user>/<project>
'ghq' list [-p] [-e] [<query>]
'ghq' look <project> | <user>/<project> | <host>/<user>/<project>
'ghq' import starred [-u] <user>
'ghq' import pocket [-u]

== COMMANDS

get::
    Clone a GitHub repository under ghq root directory. See
    <<directory-structures,DIRECTORY STRUCTURES>> below. If the repository is
    already cloned to local, nothing will happen unless '-u' ('--update')
    flag is supplied, in which case 'git remote update' is executed. +
    If there are multiple +ghq.root+ 's, existing local clones are searched
    first. Then a new repository clone is created under the primary root if
    none is found. +
    Currently supports GitHub and Google Code Project (Git/Mercurial) repositories.

list::
    List locally cloned repositories. If a query argument is given, only
    repositories whose names contain that query text are listed. '-e'
    ('--exact') forces the match to be an exact one (i.e. the query equals to
    _project_ or _user_/_project_) If '-p' ('--full-path') is given, the full paths
    to the repository root are printed instead of relative ones.

look::
    Look into a locally cloned repository with the shell.

import starred::
    Retrieves GitHub repositories that are starred by the user specified and
    performs 'get' for each of them.

import pocket::
    Retrieves http://getpocket.com/[Pocket] entries of github.com and
    performs 'get' for each of them. +
    To use this, needs to be compiled with Pocket consumer key. See <<installing,INSTALLING>>.

== CONFIGURATION

Configuration uses 'git-config' variables.

ghq.root::
    The path to directory under which cloned repositories are placed. See
    <<directory-structures,DIRECTORY STRUCTURES>> below. Defaults to +~/.ghq+. +
    This variable can have multiple values. If so, the first one becomes
    primary one i.e. new repository clones are always created under it. You may
    want to specify "$GOPATH/src" as a secondary root (environment variables
    should be expanded.)

== [[directory-structures]]DIRECTORY STRUCTURES

Local repositories are placed under 'ghq.root' with named github.com/_user_/_repo_.

....
~/.ghq
|-- code.google.com/
|   `-- p/
|       `-- vim/
`-- github.com/
    |-- codegangsta/
    |   `-- cli/
    |-- google/
    |   `-- go-github/
    `-- motemen/
        `-- ghq/
....


== [[installing]]INSTALLING

----
go get github.com/motemen/ghq
----

Or clone the https://github.com/motemen/ghq[repository] and run:

----
make install
----

If you want to enable http://getpocket.com/[Pocket] importing feature:

----
go get -ldflags "-X github.com/motemen/ghq/pocket.ConsumerKey <your Pocket consumer key>" github.com/motemen/ghq
----

Or using Makefile:

----
make install POCKET_CONSUMER_KEY=<your Pocket consumer key>
----

== AUTHOR

motemen <motemen@gmail.com>