gfork

Finds the GitHub repository of the NPM module, forks it under your account, and clones your forked repo.

$ gfork express
Forking "expressjs/express" -> "<you>/express"
Cloning into '~/gfork/express'
Running 'npm link' in '~/gfork/express'
Running 'npm link express' in <current-dir>

Installation

npm install -g gfork

Usage

gfork express

In its simplest form it:

1. Finds the GitHub repository

2. Clones it in ~/gfork/<repo>

3. If it's an npm project, npm-links accordingly

Forking

If you let it authenticate to GitHub it can also fork the repo under your account.

Or you can pass your --username=xxx and --forked flag and it'll assume that you've forked on your own.

Forking a repo creates 2 sources in the cloned repo

• origin - your fork
• src - original repo

And 2 branches:

• master - tracks origin
• src - tracks src

This lets you push your changes to your own fork, and allows you to pull in latest changes from original repo easily as well:

git checkout src
git pull

Authentication

You can authenticate either via a token or your credentials (username/password/OTP).

*Note: GitHub is deprecating password authentication, in the future you may have no other option but to get the token manually.

Settings

Settings are stored as plain JSON in ~/gfork/config.json and you can edit or save new settings. Stored settings are applied on every use, and can be overridden by command-line arguments.

Commands

In addition to the default command, it has 2 extra commands (that works only on forked repos):

Use these commands in the cloned directory:

fetch

Fetch a PR from source remote. (E.g.: "git fetch src pull/42/head:#42")

E.g.:

gfork fetch 42

pr

Create a pull request on original source using your (current) branch

E.g.:

gfork pr

Inside a fork (~/gfork/express)

gfork fetch 42     # pulls http://github.com/expressjs/express/pull/42 as pull/42 branch
gfork pr           # opens http://github.com/expressjs/express/compare/<current-branch>

Detailed Usage

gfork <library> [directory]

Fork a library

Commands:
  gfork <library> [directory]     Fork a library  [default]
  gfork pr [branch=<current>]     Create a pull request on original source using your (current) branch
  gfork fetch <pull-request>      Fetch a PR from source remote. (E.g.: "git fetch src pull/42/head:#42")

Options:
  --help, -h          Show help  [boolean]
  --version           Show version number  [boolean]
  --library, -l       Library/URL to fork  [string]
  --directory         Directory to use for cloning'  [string] [default: "~/gfork/<repo>"]
  --clean             Remove everything in target dir before cloning  [boolean]
  --npmLink           Run 'npm link' in <directory> and 'npm link <repo>' in <cwd> respectively  [boolean] [default: "<true if npm-package>"]
  --command, -c       Command to execute after cloning inside the repo dir  [string]
  --cwdCommand, --cc  Command to execute in current-dir (cwd) (after --command exits cleanly)  [string]
  --token             GitHub token  [string]
  --tokenNote         Note to use when getting token  [string] [default: "Token for gfork"]
  --config            File(s) to save config and token for future  [array] [default: ["~/gfork/config.json",".gfork"]]
  --fork              Create a fork of the repo under your GitHub account  [boolean]
  --username          GitHub username (to fetch token, and to set for cloned git repo)  [string]
  --password          GitHub password (to fetch token)  [string]
  --otp               GitHub 2FA OTP (to fetch token)  [string]
  --email             Email to set for cloned git repo  [string]
  --skipAuth          Skip GitHub authentication (don't prompt)  [boolean]
  --setUser           Set username/email in forked git repo from GitHub account  [boolean]
  --remote, -r        Remote name to use for original library  [string] [default: "src"]
  --domain, -d        In case you use something like 'acc1.github.com' in your SSH config  [string] [default: "github.com"]
  --http              Use web url (https://) (instead of ssh/git)')  [boolean]
  --depth             Create shallow clone of that depth (applied to git command)  [number]
  --branch, -b        Local branch to use  [string] [default: "master"]
  --pullRequest       PR to fetch  [number]
  --cwd               Current working directory  [string] [default: "<cwd>"]
  --silent, -s        Don't log unnecessarily  [boolean]
  --debug, -s         Log debug messages  [boolean]
  --prompt            Prompt user for missing information  [boolean] [default: "<isTTY>"]
  --confirm           Confirm decisions (only works if prompt=true)  [boolean]

Limitations

Doesn't work on Lerna packages, like babel-register.

Similar projects

	gfork	forked	git-fork	sgit
Forks	x	x	x
Auto-retrieves token	-¹		x
Clones	x		x	x
Opens a PR	x		x
Fetches a PR	x
Works on GitHub URLs	x	x	x	x
Works on NPM package names	x
Works on Bitbucket URLs				x
Works on Gitlab URLs				x
Https .git url type	x		o²
Shallow clone	x
rm -rf before cloning	x
Execute commands afterwards	x
Use saved config	x

^{-¹: for the time being... GitHub is deprecating the API that makes this possible o²: only https urls}

Non-similar but relevant projects:

• npmgitdev

Not related in any way, but nice little libraries for testing:

• rtyley/small-test-repo
• noop4