Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 421 lines (275 sloc) 7.999 kb
ff437f2 @c9s add options, update readme
authored
1 # App::gh
2797ed2 @c9s Update doc
authored
2
ab55f83 @c9s Update documentation
authored
3 App::gh is an utility helps you operate commands through
4 GitHub's API, currently App::gh is migrating to GitHub API v3.
5
6
7 ## Installation
8
9 App::gh is written in Perl, so you might need a cpanminus to
10 install CPAN modules, to install cpanminus:
11
2a33179 @c9s Syntax highlight
authored
12 ```bash
ab55f83 @c9s Update documentation
authored
13 $ curl -L http://cpanmin.us | perl - --sudo App::cpanminus
2a33179 @c9s Syntax highlight
authored
14 ```
ab55f83 @c9s Update documentation
authored
15
16 Now you have `cpanm`, you can install App::gh
17
2a33179 @c9s Syntax highlight
authored
18 ```bash
ffb90a0 @c9s Update documentation for clone command
authored
19 $ sudo cpanm https://github.com/c9s/App-gh/zipball/develop
2a33179 @c9s Syntax highlight
authored
20 ```
ab55f83 @c9s Update documentation
authored
21
22 ## Setup
23
f9a323c @c9s Setup part
authored
24 To use App::gh, you need to configure your password or OAuth
25 token in your `.gitconfig` file, just drop the lines below
26 to setup your password:
27
04561da @c9s Merge branch 'master' into develop
authored
28 ```ini
f9a323c @c9s Setup part
authored
29 [github]
04561da @c9s Merge branch 'master' into develop
authored
30 user = c9s
31 password = your password
32 ```
f9a323c @c9s Setup part
authored
33
ffb90a0 @c9s Update documentation for clone command
authored
34 To use OAuth token, you need to set your OAuth access token:
35
2a33179 @c9s Syntax highlight
authored
36 ```ini
ffb90a0 @c9s Update documentation for clone command
authored
37 [github]
38 user = c9s
39 access_token = SHA1601f1889667efaebb33b8c12572835da3f027f78
2a33179 @c9s Syntax highlight
authored
40 ```
ffb90a0 @c9s Update documentation for clone command
authored
41
ab55f83 @c9s Update documentation
authored
42 ## Commands
ff437f2 @c9s add options, update readme
authored
43
44 ### clone
9481c04 @c9s Update readme
authored
45
a33ca69 @c9s Fix doc
authored
46 To clone a repository, use below command form:
ffb90a0 @c9s Update documentation for clone command
authored
47
2a33179 @c9s Syntax highlight
authored
48 ```bash
a33ca69 @c9s Fix doc
authored
49 $ gh clone [user]/[repo]
50 $ gh clone [user] [repo]
2a33179 @c9s Syntax highlight
authored
51 ```
9481c04 @c9s Update readme
authored
52
ffb90a0 @c9s Update documentation for clone command
authored
53 When cloning repository from others, the default URI is
54 HTTP, which is `read-only`.
9481c04 @c9s Update readme
authored
55
ffb90a0 @c9s Update documentation for clone command
authored
56 When cloning repository from yourself, the default URI is
57 SSH, which is `read & write`.
58
59 To specify URI type, you can simply pass options like
60 `--http` for HTTP, `--https` for HTTPS, `--ssh` for SSH,
61 `--ro` for read-only URI. e.g.:
9481c04 @c9s Update readme
authored
62
2a33179 @c9s Syntax highlight
authored
63 ```bash
ff437f2 @c9s add options, update readme
authored
64 $ gh clone miyagawa Plack
9481c04 @c9s Update readme
authored
65
ffb90a0 @c9s Update documentation for clone command
authored
66 $ gh clone user repo --http
67
68 $ gh clone user repo --https
9481c04 @c9s Update readme
authored
69
ffb90a0 @c9s Update documentation for clone command
authored
70 $ gh clone user repo --ssh
846ef18 @c9s Update readme
authored
71
ff437f2 @c9s add options, update readme
authored
72 $ gh clone clkao Web-Hippie --ro
2a33179 @c9s Syntax highlight
authored
73 ```
9481c04 @c9s Update readme
authored
74
a33ca69 @c9s Fix doc
authored
75 Clone from SSH URI:
9481c04 @c9s Update readme
authored
76
2a33179 @c9s Syntax highlight
authored
77 ```bash
ffb90a0 @c9s Update documentation for clone command
authored
78 $ gh clone miyagawa/Plack --ssh
2a33179 @c9s Syntax highlight
authored
79 ```
9481c04 @c9s Update readme
authored
80
ffb90a0 @c9s Update documentation for clone command
authored
81 To fetch related remote of forks, you can specify
82 `--forks` option. this command allows you to download
83 commits from others' fork.
9481c04 @c9s Update readme
authored
84
2a33179 @c9s Syntax highlight
authored
85 ```bash
ffb90a0 @c9s Update documentation for clone command
authored
86 $ gh clone c9s App-gh --forks
2a33179 @c9s Syntax highlight
authored
87 ```
9481c04 @c9s Update readme
authored
88
bf80154 @c9s Add origin
authored
89 To clone repository and set the default remote name instead
90 of `origin`, you can specify `--origin` option:
91
2a33179 @c9s Syntax highlight
authored
92 ```bash
bf80154 @c9s Add origin
authored
93 $ gh clone c9s App-gh --origin github
2a33179 @c9s Syntax highlight
authored
94 ```
bf80154 @c9s Add origin
authored
95
ff437f2 @c9s add options, update readme
authored
96 ### all
9481c04 @c9s Update readme
authored
97
4ce2ccf @c9s More usage examples
authored
98 By using the `all` command, you can clone all repositories
99 from an user.
100
101 Below is the basic form:
102
2a33179 @c9s Syntax highlight
authored
103 ```bash
4ce2ccf @c9s More usage examples
authored
104 $ gh all [user] [type]
2a33179 @c9s Syntax highlight
authored
105 ```
4ce2ccf @c9s More usage examples
authored
106
2a33179 @c9s Syntax highlight
authored
107 The `[type]` can be `member`, `all`, `owner`. if you specify
4ce2ccf @c9s More usage examples
authored
108 `all` then all repositories including fork projects will be
109 cloned. if you specify `owner`, then only the owner's
110 projects will be cloned.
111
112 For example, to clone all repositories of miyagawa:
9481c04 @c9s Update readme
authored
113
2a33179 @c9s Syntax highlight
authored
114 ```bash
ded5f8f @DarwinAwardWinner Fix *all* trailing whitespace and blank line before =head1
DarwinAwardWinner authored
115 $ gh all miyagawa
2a33179 @c9s Syntax highlight
authored
116 ```
9481c04 @c9s Update readme
authored
117
4ce2ccf @c9s More usage examples
authored
118 To clone all repositories that owned by facebook:
119
2a33179 @c9s Syntax highlight
authored
120 ```bash
4ce2ccf @c9s More usage examples
authored
121 $ gh all facebook owner
2a33179 @c9s Syntax highlight
authored
122 ```
4ce2ccf @c9s More usage examples
authored
123
124 By specifing `--into` option, you can clone these
125 repositories into a specific directory, for example:
126
2a33179 @c9s Syntax highlight
authored
127 ```bash
4ce2ccf @c9s More usage examples
authored
128 $ gh all facebook owner --into path/to/facebook
5e807d4 @c9s Update readme
authored
129
ff437f2 @c9s add options, update readme
authored
130 $ gh all perl6 --into perl6-stuff
2a33179 @c9s Syntax highlight
authored
131 ```
5e807d4 @c9s Update readme
authored
132
4ce2ccf @c9s More usage examples
authored
133 To prompt before cloning each repository:
134
2a33179 @c9s Syntax highlight
authored
135 ```bash
4ce2ccf @c9s More usage examples
authored
136 $ gh all perl6 --prompt
2a33179 @c9s Syntax highlight
authored
137 ```
4ce2ccf @c9s More usage examples
authored
138
139 To also fetch tags, you can specify `--tags` option:
140
2a33179 @c9s Syntax highlight
authored
141 ```bash
4ce2ccf @c9s More usage examples
authored
142 $ gh all facebook --tags
2a33179 @c9s Syntax highlight
authored
143 ```
4ce2ccf @c9s More usage examples
authored
144
145 You can also specify a prefix to each repo:
e3b2ac7 @c9s --prompt option
authored
146
2a33179 @c9s Syntax highlight
authored
147 ```bash
4ce2ccf @c9s More usage examples
authored
148 $ gh all facebook --prefix=facebook-prefix-
2a33179 @c9s Syntax highlight
authored
149 ```
e3b2ac7 @c9s --prompt option
authored
150
4ce2ccf @c9s More usage examples
authored
151 To clone these repositories as bared:
9481c04 @c9s Update readme
authored
152
2a33179 @c9s Syntax highlight
authored
153 ```bash
4ce2ccf @c9s More usage examples
authored
154 $ gh all facebook --bare
2a33179 @c9s Syntax highlight
authored
155 ```
2f70db9 @c9s HTML comment mark
authored
156
3d1ed09 @c9s Add --recursive option doc
authored
157 To recursively clone submodules:
158
2a33179 @c9s Syntax highlight
authored
159 ```bash
3d1ed09 @c9s Add --recursive option doc
authored
160 $ gh all perl6 --recursive
2a33179 @c9s Syntax highlight
authored
161 ```
3d1ed09 @c9s Add --recursive option doc
authored
162
9b30638 @c9s Import command now works
authored
163
164 ### import
165
166 By using the `import` command, you can import your git
167 repository to your GitHub account.
168
169 You can simply type below line the upload your project:
170
2a33179 @c9s Syntax highlight
authored
171 ```bash
9b30638 @c9s Import command now works
authored
172 $ gh import
2a33179 @c9s Syntax highlight
authored
173 ```
9b30638 @c9s Import command now works
authored
174
175 To specify remote name for GitHub, you can use `--remote`
176 option.
177
2a33179 @c9s Syntax highlight
authored
178 ```bash
9b30638 @c9s Import command now works
authored
179 $ gh import --remote github
2a33179 @c9s Syntax highlight
authored
180 ```
9b30638 @c9s Import command now works
authored
181
e6aa009 @c9s Fix wrap
authored
182 ### search
183
184 To search repositories, simply use `search` command:
185
2a33179 @c9s Syntax highlight
authored
186 ```bash
e6aa009 @c9s Fix wrap
authored
187 $ gh search keyword
2a33179 @c9s Syntax highlight
authored
188 ```
9b30638 @c9s Import command now works
authored
189
2be6ac9 @c9s describe update command.
authored
190 ### update
191
192 Sometimes you need to update remote refs, branches, tags,
193 you might run `git remote update --prune`, and run pull with
194 --rebase option to rebase changes on your local branch.
195
196 With App::gh, you can do simpler with the `update` command.
197
198 ```bash
199 $ gh update
200 ```
201
202 The command above actually runs:
203
204 ```bash
205 git remote update --prune
206 git remote | while read remote; do
207 git pull --rebase $remote $(git rev-parse --abbrev-ref HEAD)
208 done
209 ```
210
2f70db9 @c9s HTML comment mark
authored
211 <!--
ff437f2 @c9s add options, update readme
authored
212 ### fork
9481c04 @c9s Update readme
authored
213
ff437f2 @c9s add options, update readme
authored
214 to fork project:
9481c04 @c9s Update readme
authored
215
ff437f2 @c9s add options, update readme
authored
216 $ gh fork clkao AnyMQ
9481c04 @c9s Update readme
authored
217
ff437f2 @c9s add options, update readme
authored
218 to fork current project:
b63eef0 @c9s Update README
authored
219
ff437f2 @c9s add options, update readme
authored
220 $ cd clkao/AnyMQ
221 $ gh fork
9481c04 @c9s Update readme
authored
222
af3b2ce @c9s Update readme
authored
223 ### network
9481c04 @c9s Update readme
authored
224
ff437f2 @c9s add options, update readme
authored
225 to show fork network:
9481c04 @c9s Update readme
authored
226
ff437f2 @c9s add options, update readme
authored
227 $ cd App-gh/
228 $ gh network
229 c9s/App-gh - watchers(4) forks(1)
b62c245 @c9s Replace examples
authored
230 foo/App-gh - watchers(1) forks(0)
2797ed2 @c9s Update doc
authored
231
af3b2ce @c9s Update readme
authored
232 ### pull
233
234 Pull command behavior
235
1531aa6 @c9s Update readme
authored
236 - Add remote for a fork
237 - Fetch remote
238 - Merge from fork branch if --merge option is specified.
239 - Create a branch if --branch is specified.
af3b2ce @c9s Update readme
authored
240
1531aa6 @c9s Update readme
authored
241 First , switch path to your repository:
af3b2ce @c9s Update readme
authored
242
243 $ cd App-gh/
244
1531aa6 @c9s Update readme
authored
245 Show up the network by running pull command with no arguments:
246
247 $ gh pull
ded5f8f @DarwinAwardWinner Fix *all* trailing whitespace and blank line before =head1
DarwinAwardWinner authored
248 ....
1531aa6 @c9s Update readme
authored
249
b62c245 @c9s Replace examples
authored
250 To pull from foo and add remote:
af3b2ce @c9s Update readme
authored
251
b62c245 @c9s Replace examples
authored
252 $ gh pull foo
253 $ git log foo/master # to show changes
af3b2ce @c9s Update readme
authored
254
b62c245 @c9s Replace examples
authored
255 To pull from foo and merge changes:
af3b2ce @c9s Update readme
authored
256
b62c245 @c9s Replace examples
authored
257 $ gh pull foo -m
af3b2ce @c9s Update readme
authored
258
ded5f8f @DarwinAwardWinner Fix *all* trailing whitespace and blank line before =head1
DarwinAwardWinner authored
259 To merge foo/feature1 to local/master
af3b2ce @c9s Update readme
authored
260
b62c245 @c9s Replace examples
authored
261 $ gh pull foo feature1 -m
1531aa6 @c9s Update readme
authored
262
b62c245 @c9s Replace examples
authored
263 To merge changes from foo/master and create a tracked branch:
1531aa6 @c9s Update readme
authored
264
b62c245 @c9s Replace examples
authored
265 $ gh pull foo --merge --branch
266 $ gh pull foo -m -b
1531aa6 @c9s Update readme
authored
267
af3b2ce @c9s Update readme
authored
268
c55db11 @c9s Pull requests
authored
269 ### Pull Requests: pullreq
35b6735 @mattn added pod.
mattn authored
270
271 To show pull requests of the project:
272
273 $ cd tokuhirom/Amon
274 $ gh pullreq list
275
dc9330c @c9s Update readme
authored
276 * Issue 1: Test - Cornelius (c9s)
277 Diff: https://github.com/c9s/App-gh/pull/29.diff
278 Body: Test
279 * Issue 2: Test - Cornelius (c9s)
280 Diff: https://github.com/c9s/App-gh/pull/29.diff
281 Body: Test
282 ...
283
35b6735 @mattn added pod.
mattn authored
284 And show the pull request
285
286 $ cd gfx/p5-Text-Xslate
287 $ gh pullreq show 3
288
289 If you want to send pull request about current branch:
290
291 $ cd yappo/p5-AnySan
292 $ git checkout -b experimental
293 $ vi lib/AnySan.pm
294 $ git commit -m "bug fix about ..."
295 $ gh pullreq send
296
dc9330c @c9s Update readme
authored
297 ### update
298
299 Run (pull/push) repository changes from/to remotes, and `git remote update --prune`
300
301 $ gh update
302
8228346 @mattn added pod.
mattn authored
303 ### issue
304
305 To show issues of the project:
306
307 $ cd mattn/p5-Growl-Any
308 $ gh issue list
309
310 And show the issue
311
312 $ cd mattn/p5-Growl-GNTP
313 $ gh issue show 3
314
315 If you want to create issue:
316
317 $ cd mattn/p5-Growl-GNTP
318 $ gh issue edit
319
320 Or edit issue
321
322 $ gh issue edit 3
323
324 And comment to the issue
325
326 $ gh issue comment 3
327
49ba5c6 @c9s Rename Cloneall to All. update command aliases
authored
328 ## COMMAND ALIAS
329
330 "a" => "all"
8228346 @mattn added pod.
mattn authored
331 "ci" => "commit"
35b6735 @mattn added pod.
mattn authored
332 "fo" => "fork"
8228346 @mattn added pod.
mattn authored
333 "is" => "issue"
35b6735 @mattn added pod.
mattn authored
334 "ne" => "network"
8228346 @mattn added pod.
mattn authored
335 "pr" => "pullreq"
336 "pu" => "pull"
35b6735 @mattn added pod.
mattn authored
337 "se" => "search"
8228346 @mattn added pod.
mattn authored
338 "up" => "update"
2f70db9 @c9s HTML comment mark
authored
339 -->
49ba5c6 @c9s Rename Cloneall to All. update command aliases
authored
340
4e0fb85 @c9s markdown syntax
authored
341 ## INSTALLATION
2797ed2 @c9s Update doc
authored
342
343 To install this module, run the following commands:
344
b63eef0 @c9s Update README
authored
345 # Makefile.PL needs this
346 cpan Module::Install::AuthorTests
347
2797ed2 @c9s Update doc
authored
348 perl Makefile.PL
349 make
350 make test
351 make install
352
4c71c9f @c9s update readme
authored
353 ## COMPLETION
354
355 ### zsh
356
357 $ mkdir ~/.zsh/functions
358 $ cp completion/zsh/_gh ~/.zsh/functions
ded5f8f @DarwinAwardWinner Fix *all* trailing whitespace and blank line before =head1
DarwinAwardWinner authored
359
4c71c9f @c9s update readme
authored
360 add ~/.zsh/functions to your fpath
361
362 $ vim ~/.zshrc
363
364 fpath=(~/.zsh/functions/ $fpath)
365
4e0fb85 @c9s markdown syntax
authored
366 ## DEVELOPMENT
367
368 please keep the dependency simple and less.
369
5e356f9 @c9s Update contributor list
authored
370
371 ## CONTRIBUTORS
372
373 Alexandr Ciornii alexchorny@gmail.com
374 Breno G. de Oliveira garu@cpan.org
375 Chris Weyl cweyl@alumni.drew.edu
376 Fuji, Goro gfuji@cpan.org
377 Ryan C. Thompson rct@thompsonclan.org
378 Tokuhiro Matsuno tokuhirom@gmail.com
379 Yo-An Lin cornelius.howl@gmail.com
380 Zak B. Elep zakame@zakame.net
381 c9s cornelius.howl@gmail.com
382 chocolateboy chocolate@cpan.org
383 mattn mattn.jp@gmail.com
384 tokuhirom tokuhirom@gmail.com
385 tyru tyru.exe@gmail.com
386 xaicron xaicron@gmail.com
387 yj liyuray@gmail.com
388
4e0fb85 @c9s markdown syntax
authored
389 ## SUPPORT AND DOCUMENTATION
2797ed2 @c9s Update doc
authored
390
391 After installing, you can find documentation for this module with the
392 perldoc command.
393
009357c @c9s rename gh
authored
394 perldoc App::gh
2797ed2 @c9s Update doc
authored
395
396 You can also look for information at:
397
398 RT, CPAN's request tracker
009357c @c9s rename gh
authored
399 http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-gh
2797ed2 @c9s Update doc
authored
400
401 AnnoCPAN, Annotated CPAN documentation
009357c @c9s rename gh
authored
402 http://annocpan.org/dist/App-gh
2797ed2 @c9s Update doc
authored
403
404 CPAN Ratings
009357c @c9s rename gh
authored
405 http://cpanratings.perl.org/d/App-gh
2797ed2 @c9s Update doc
authored
406
407 Search CPAN
009357c @c9s rename gh
authored
408 http://search.cpan.org/dist/App-gh/
2797ed2 @c9s Update doc
authored
409
410
4e0fb85 @c9s markdown syntax
authored
411 ## LICENSE AND COPYRIGHT
2797ed2 @c9s Update doc
authored
412
413 Copyright (C) 2010 Cornelius
414
415 This program is free software; you can redistribute it and/or modify it
416 under the terms of either: the GNU General Public License as published
417 by the Free Software Foundation; or the Artistic License.
418
419 See http://dev.perl.org/licenses/ for more information.
420
Something went wrong with that request. Please try again.