From 2b73d4faed448817b3b6b5754c1e514017e055ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mislav=20Marohni=C4=87?= Date: Fri, 28 Dec 2018 07:21:03 +0100 Subject: [PATCH] Document how we scan git remotes and branch tracking information --- commands/pull_request.go | 10 +++++++--- share/man/man1/hub.1.ronn | 31 +++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+), 3 deletions(-) diff --git a/commands/pull_request.go b/commands/pull_request.go index c56eebd7..e1e53b4a 100644 --- a/commands/pull_request.go +++ b/commands/pull_request.go @@ -60,11 +60,15 @@ pull-request -i Push the current branch to before creating the pull request. -b, --base= - The base branch in "[OWNER:]BRANCH" format. Defaults to the default branch - (usually "master"). + The base branch in the "[:]" format. Defaults to the default + branch of the upstream repository (usually "master"). + + See the "CONVENTIONS" section of hub(1) for more information on how hub + selects the defaults in case of multiple git remotes. -h, --head= - The head branch in "[OWNER:]BRANCH" format. Defaults to the current branch. + The head branch in "[:]" format. Defaults to the currently + checked out branch. -r, --reviewer= A comma-separated list of GitHub handles to request a review from. diff --git a/share/man/man1/hub.1.ronn b/share/man/man1/hub.1.ronn index 6f76530c..8416f328 100644 --- a/share/man/man1/hub.1.ronn +++ b/share/man/man1/hub.1.ronn @@ -88,6 +88,37 @@ git but that are extended through hub, and custom ones that hub provides. * hub-sync(1): Fetch from upstream and update local branches. +## CONVENTIONS + +Most hub commands are supposed to be run in a context of an existing local git +repository. Hub will automatically detect the GitHub repository the current +project belongs to by scanning its git remotes. + +In case there are multiple git remotes that are all pointing to GitHub, hub +assumes that the main one is named "upstream", "github", or "origin", in that +order of preference. + +When working with forks, it's recommended that the git remote for your own fork +is named "origin" and that the git remote for the upstream repository is named +"upstream". See + +The default branch (usually "master") for the project is detected like so: + + git symbolic-ref refs/remotes/origin/HEAD + +where is the name of the git remote for the upstream repository. + +The destination where the currently checked out branch is considered to be +pushed to depends on the `git config push.default` setting. If the value is +"upstream" or "tracking", the tracking information for a branch is read like so: + + git rev-parse --symbolic-full-name BRANCH@{upstream} + +Otherwise, hub scans git remotes to find the first one for which +`refs/remotes/REMOTE/BRANCH` exists. The "origin", "github", and "upstream" +remotes are searched last because hub assumes that it's more likely that the +current branch is pushed to your fork rather than to the canonical repo. + ## CONFIGURATION ### GitHub OAuth authentication