github-clone.el

github-clone.el copied to clipboard

#+TITLE: github-clone.el #+AUTHOR: Charles L.G. Comstock #+EMAIL: [email protected]

• Introduction

Easily clone github repos, and optionally fork a copy with the remote named after the users github username.

[[http://melpa.org/#/github-clone][file:http://melpa.org/packages/github-clone-badge.svg]] [[https://circleci.com/gh/dgtized/github-clone.el][https://circleci.com/gh/dgtized/github-clone.el.svg?style=svg]]

• Usage

~M-x github-clone~ will prompt for a repository and directory and clone the repository as origin to that directory. It will then optionally fork the repo and add a remote named after the github user.

As example:

#+BEGIN_SRC emacs-lisp (github-clone "dgtized/github-clone.el" "~") #+END_SRC

[[https://github.com/sigma/gh.el][gh.el]] will prompt for a github username and password to generate an oauth key. See documentation on [[https://github.com/defunkt/gist.el][gist.el]] and [[*GitHub%20API][GitHub API]] for more details.

After creating an API key, =dgtized/github-clone.el= will be cloned into ~$HOME/github-clone.el~ as remote =origin=. It will then prompt if the repository should be forked. If so, it will fork the repository to the user authorized by the API key. Finally a remote named after the github user will added to the local repository.

** Adding Remotes

The function =github-clone-add-existing-remote= will prompt for a remote, find all forks of that remote on github, and then prompt to add any of those forks as a named remote. As example, in a checkout of this repo, running;

: M-x github-clone-add-existing-remote [RET] origin

Will execute a =completing-read= prompting to add a fork of =github-clone.el= as a new remote.

Similarly, =github-clone-add-parent-remote= and =github-clone-add-source-remote= can be used to add a parent or source remote.

These are convenience methods which make it easier to add collaborating repos as remotes in order to fetch branches and test pull requests.

• Install

github-clone.el uses [[https://github.com/sigma/gh.el][gh.el]] as a dependency, so it's easiest to install via package.el.

** Via Package.el

Using the [[https://melpa.org][MELPA]] package archive,

: M-x package-install [RET] github-clone [RET]

Or manually by downloading [[https://github.com/dgtized/github-clone.el/blob/master/github-clone.el][github-clone.el]],

: $ wget https://raw.githubusercontent.com/dgtized/github-clone.el/master/github-clone.el

And then from emacs:

: M-x package-install-file path/to/github-clone.el

• GitHub API Keys

[[https://github.com/sigma/gh.el][gh.el]] uses =~/.gitconfig= to store the API keys. When the key is created it will store the key at the end of =~/.gitconfig=.

** Permissions and Revoking

If [[gh.el]] has trouble generating an API key, or it is necessary to revoke the API key, visit [[https://github.com/settings/applications][Application Settings]]. Generate a new personal access token with permissions for =repo=, and =user=. Include permissions for =gist= to maintain compatibility with [[https://github.com/defunkt/gist.el][gist.el]].

** Securing the keys

=~/.gitconfig= is a useful dotfile to version in a git repository. So how can we avoid storing API keys in the dotfile repo? Move the API configuration into =~/.gitconfig.private=.

#+BEGIN_EXAMPLE [github] user = $USER oauth-token = $KEY #+END_EXAMPLE

Replace the API keys configuration in =~/.gitconfig= with the inclusion below.

#+BEGIN_EXAMPLE [include] path = ~/.gitconfig.private #+END_EXAMPLE