# App::gh

App::gh is an utility helps you operate commands through
GitHub's API, currently App::gh is migrating to GitHub API v3.


## Installation

App::gh is written in Perl, so you might need a cpanminus to
install CPAN modules, to install cpanminus:

```bash
    $ curl -L http://cpanmin.us | perl - --sudo App::cpanminus
```

Now you have `cpanm`, you can install App::gh

```bash
    $ sudo cpanm https://github.com/c9s/App-gh/zipball/develop
```

## Setup

To use App::gh, you need to configure your password or OAuth
token in your `.gitconfig` file, just drop the lines below
to setup your password:

```ini
    [github]
        user = c9s
        password = your password
```

To use OAuth token, you need to set your OAuth access token:

```ini
    [github]
        user = c9s
        access_token = SHA1601f1889667efaebb33b8c12572835da3f027f78
```

## Commands

### clone

To clone a repository, use below command form:

```bash
    $ gh clone [user]/[repo]
    $ gh clone [user] [repo]
```

When cloning repository from others, the default URI is 
HTTP, which is `read-only`.

When cloning repository from yourself, the default URI is 
SSH, which is `read & write`.

To specify URI type, you can simply pass options like 
`--http` for HTTP, `--https` for HTTPS, `--ssh` for SSH,
`--ro` for read-only URI.  e.g.:

```bash
    $ gh clone miyagawa Plack

    $ gh clone user repo --http

    $ gh clone user repo --https

    $ gh clone user repo --ssh

    $ gh clone clkao Web-Hippie --ro
```

Clone from SSH URI:

```bash
    $ gh clone miyagawa/Plack --ssh
```

To fetch related remote of forks, you can specify
`--forks` option. this command allows you to download 
commits from others' fork.

```bash
    $ gh clone c9s App-gh --forks
```

To clone repository and set the default remote name instead 
of `origin`, you can specify `--origin` option:

```bash
    $ gh clone c9s App-gh --origin github
```

### all

By using the `all` command, you can clone all repositories
from an user.

Below is the basic form:

```bash
    $ gh all [user] [type]
```

The `[type]` can be `member`, `all`, `owner`. if you specify 
`all` then all repositories including fork projects will be 
cloned. if you specify `owner`, then only the owner's
projects will be cloned.

For example, to clone all repositories of miyagawa:

```bash
    $ gh all miyagawa
```

To clone all repositories that owned by facebook:

```bash
    $ gh all facebook owner
```

By specifing `--into` option, you can clone these 
repositories into a specific directory, for example:

```bash
    $ gh all facebook owner --into path/to/facebook

    $ gh all perl6 --into perl6-stuff
```

To prompt before cloning each repository:

```bash
    $ gh all perl6 --prompt
```

To also fetch tags, you can specify `--tags` option:

```bash
    $ gh all facebook --tags
```

You can also specify a prefix to each repo:

```bash
    $ gh all facebook --prefix=facebook-prefix-
```

To clone these repositories as bared:

```bash
    $ gh all facebook --bare
```

To recursively clone submodules:

```bash
    $ gh all perl6 --recursive
```


### import

By using the `import` command, you can import your git
repository to your GitHub account.

You can simply type below line the upload your project:

```bash
    $ gh import
```

To specify remote name for GitHub, you can use `--remote`
option.

```bash
    $ gh import --remote github
```

### search

To search repositories, simply use `search` command:

```bash
    $ gh search keyword
```

### update

Sometimes you need to update remote refs, branches, tags,
you might run `git remote update --prune`, and run pull with
--rebase option to rebase changes on your local branch.

With App::gh, you can do simpler with the `update` command.

```bash
    $ gh update
```

The command above actually runs:

```bash
    git remote update --prune
    git remote | while read remote; do
        git pull --rebase $remote $(git rev-parse --abbrev-ref HEAD)
    done
```

<!--
### fork

to fork project:

    $ gh fork clkao AnyMQ

to fork current project:

    $ cd clkao/AnyMQ
    $ gh fork

### network

to show fork network:

    $ cd App-gh/
    $ gh network
        c9s/App-gh - watchers(4) forks(1)
      foo/App-gh - watchers(1) forks(0)

### pull

Pull command behavior

    - Add remote for a fork
    - Fetch remote
    - Merge from fork branch if --merge option is specified.
    - Create a branch if --branch is specified.

First , switch path to your repository:

    $ cd App-gh/

Show up the network by running pull command with no arguments:

    $ gh pull
    ....

To pull from foo and add remote:

    $ gh pull foo
    $ git log foo/master   # to show changes

To pull from foo and merge changes:

    $ gh pull foo -m

To merge foo/feature1 to local/master

    $ gh pull foo feature1 -m

To merge changes from foo/master and create a tracked branch:

    $ gh pull foo --merge --branch
    $ gh pull foo -m -b


### Pull Requests: pullreq

To show pull requests of the project:

    $ cd tokuhirom/Amon
    $ gh pullreq list

    * Issue 1: Test - Cornelius (c9s)
      Diff: https://github.com/c9s/App-gh/pull/29.diff
      Body: Test
    * Issue 2: Test - Cornelius (c9s)
      Diff: https://github.com/c9s/App-gh/pull/29.diff
      Body: Test
      ...

And show the pull request

    $ cd gfx/p5-Text-Xslate
    $ gh pullreq show 3

If you want to send pull request about current branch:

    $ cd yappo/p5-AnySan
    $ git checkout -b experimental
    $ vi lib/AnySan.pm
    $ git commit -m "bug fix about ..."
    $ gh pullreq send

### update

Run (pull/push) repository changes from/to remotes, and `git remote update --prune`

    $ gh update

### issue

To show issues of the project:

    $ cd mattn/p5-Growl-Any
    $ gh issue list

And show the issue

    $ cd mattn/p5-Growl-GNTP
    $ gh issue show 3

If you want to create issue:

    $ cd mattn/p5-Growl-GNTP
    $ gh issue edit

Or edit issue

    $ gh issue edit 3

And comment to the issue

    $ gh issue comment 3

## COMMAND ALIAS

    "a"  => "all"
    "ci" => "commit"
    "fo" => "fork"
    "is" => "issue"
    "ne" => "network"
    "pr" => "pullreq"
    "pu" => "pull"
    "se" => "search"
    "up" => "update"
-->

## INSTALLATION

To install this module, run the following commands:

    # Makefile.PL needs this
    cpan Module::Install::AuthorTests

	perl Makefile.PL
	make
	make test
	make install

## COMPLETION

### zsh

    $ mkdir ~/.zsh/functions
    $ cp completion/zsh/_gh  ~/.zsh/functions

add ~/.zsh/functions to your fpath

    $ vim ~/.zshrc

    fpath=(~/.zsh/functions/ $fpath)

## DEVELOPMENT

please keep the dependency simple and less.


## CONTRIBUTORS

    Alexandr Ciornii alexchorny@gmail.com
    Breno G. de Oliveira garu@cpan.org
    Chris Weyl cweyl@alumni.drew.edu
    Fuji, Goro gfuji@cpan.org
    Ryan C. Thompson rct@thompsonclan.org
    Tokuhiro Matsuno tokuhirom@gmail.com
    Yo-An Lin cornelius.howl@gmail.com
    Zak B. Elep zakame@zakame.net
    c9s cornelius.howl@gmail.com
    chocolateboy chocolate@cpan.org
    mattn mattn.jp@gmail.com
    tokuhirom tokuhirom@gmail.com
    tyru tyru.exe@gmail.com
    xaicron xaicron@gmail.com
    yj liyuray@gmail.com

## SUPPORT AND DOCUMENTATION

After installing, you can find documentation for this module with the
perldoc command.

    perldoc App::gh

You can also look for information at:

    RT, CPAN's request tracker
        http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-gh

    AnnoCPAN, Annotated CPAN documentation
        http://annocpan.org/dist/App-gh

    CPAN Ratings
        http://cpanratings.perl.org/d/App-gh

    Search CPAN
        http://search.cpan.org/dist/App-gh/


## LICENSE AND COPYRIGHT

Copyright (C) 2010 Cornelius

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

