GIT-HUB(1)

📦
version 2.1.3 · 6 versions
, in ubuntu jammy, ubuntu noble

okay so bestie, meet git-hub — the ✨ Git command line interface to GitHub ✨ — and honestly? she ate. this is the git-hub(1) manual page and we're getting through all of it together, no skimming, no skipping, fr fr 💖

✨ SYNOPSIS ✨

git hub [global options] <command> [options] [arguments]

🦋 DESCRIPTION 🦋

so git hub is a simple command line interface to github, and the whole point is that most of the actually-useful GitHub tasks (like creating and listing pull requests or issues) can be hit directly through the git command line. no browser tab, no vibes-ruining clicking, just terminal. iconic. 💅

to use this command you'll probably need to do an initial configuration first, so you can get authorization from GitHub. for that you use the setup command. and if you want the whole menu of configuration options, go look at the CONFIGURATION section. 🫶

💅 GLOBAL OPTIONS 💅

  • -h, --help — show this help and exit. the classic escape hatch 🏃‍♀️
  • --version — show the program's version number and exit.
  • -v, --verbose — be more verbose. you can pass it multiple times to get extra verbosity (she will yap, and you will listen) 🗣️
  • -s, --silent — be less verbose. also stackable — pass it multiple times to get less verbosity. 🤫

👑 COMMANDS 👑

🎀 setup

this command does an initial setup so you can connect to GitHub. basically it asks for a username and a GitHub Personal Access Token (PAT), which is needed for most actions. like, most of the good stuff is locked behind that token, periodt.

the token will be stored it in the Git configuration variable hub.oauthtoken for future use. if you don't have one, you can create it (check GitHub docs if you need more help). make sure your PAT has at least repo and user scope. ⚠️

the username is also stored for future use, in the hub.username variable. and if the base URL is specified, it gets stored in hub.baseurl too.

by default the configuration is stored in the repository's .git/config file (using git config). if you want your configuration to be global to your user, or system-wide, use the --global or --system option respectively. those options get passed straight to git config. 💫

  • -u USERNAME, --username=USERNAME — GitHub's username (login name), which will be stored in the configuration variable hub.username. if an e-mail is provided, then a username matching that e-mail will be searched and used instead, if found (for this to work the e-mail must be part of the public profile). 🔍
  • -o TOKEN, --oauthtoken=TOKEN — GitHub's Personal Access Token (PAT), which will be stored in the configuration variable hub.username. if an e-mail is provided, then a username matching that e-mail will be searched and used instead, if found (for this to work the e-mail must be part of the public profile).
  • -b URL, --baseurl=URL — GitHub's base URL to use to access the API. set this when your GitHub API lives somewhere other than the default (Enterprise servers usually use https://host/api/v3).
  • --global — store settings in the global configuration (see the --global option in git config(1) for details).
  • --system — store settings in the system configuration (see the --system option in git config(1) for details).

🌸 clone REPO [DEST]

this command clones REPO, a GitHub repository, into a DEST directory (which defaults to the name of the project being cloned). if the repository is specified in <owner>/<project> form, then REPO is used as upstream and a personal fork gets looked up. if none is found, a brand new fork is created. in both cases, the fork gets cloned instead of the upstream repository. and REPO can be given as a regular clone URL too (http, ssh, git) — in that case the URL gets inspected and hub.urltype is set as appropriate. 🧚

if only <project> is specified as REPO, then the configuration hub.username is used as <owner>, and the parent repository is looked up at GitHub to figure out the real upstream repository.

the upstream repository is cloned as --upstreamremote (or hub.upstreamremote, upstream by default), the remote for the fork is added as --forkremote (or hub.forkremote, fork by default), and the fork is set as the git remote.pushdefault (so pushing will hit the fork by default) — unless --no-triangular is used (please go read that option for the details, bestie, don't skip it 👀).

after cloning and fetching, the git configuration variables hub.upstream, hub.upstreamremote and hub.forkremote are set in the newly cloned repo (see CONFIGURATION).

  • -U NAME, --upstreamremote=NAME — use NAME as the upstream remote repository name instead of the default 'upstream').
  • -F NAME, --forkremote=NAME — use NAME as the fork remote repository name instead of the default 'fork').
  • -t, --triangular — use Git's triangular workflow configuration (this is the default). this option clones from the parent/upstream repository, and adds the fork as a remote repository. then it sets the remote.pushdefault Git option and the hub.forkremote git-hub option to the just cloned repository.

the effect of this is having the upstream repository used by default when you pull, but using your fork when you push — which is typically exactly what you want when you're doing GitHub's pull requests. 💖

Git version 1.8.3 or newer is needed to use this option (and 1.8.4 or newer is recommended, because of some issues in 1.8.3 related to this). ⚠️

to change the default you can set the option hub.triangular. see CONFIGURATION for details.

  • --no-triangular — don't use Git's triangular workflow configuration (this is only available for backwards compatibility but is not recommended). this option clones from the forked repository instead of cloning the upstream/parent repo, so both pulls and pushes will be done with the fork by default.

this option could also be used to clone a GitHub repository without forking it, but heads up: some functionality of the tool will be lost. 💀

🧵 GIT CLONE OPTIONS

any standard git clone option can be passed. not all of them might make sense when you're cloning a GitHub repo to be used with this tool though.

this command will run the hub.hookscript on some events — please have a look at HOOK SCRIPT for more details. 🌈

🍓 issue

this command is used to manage GitHub issues through a set of subcommands. she's got range. 💜

📋 list

show a list of open issues.

  • -c, --closed — show closed issues instead.
  • -C, --created-by-me — show only issues created by me 🙋‍♀️
  • -A, --assigned-to-me — show only issues assigned to me

🔎 show ISSUE [ISSUE ...]

show issues identified by ISSUE.

✨ new

create a new issue.

the content of the template files ISSUE_TEMPLATE or ISSUE_TEMPLATE.md will be added to the issue message if any of those template files is found in the top-level directory of the project, the .github directory or the .git directory. the order for template file lookups matters, and it follows the order as described above for template file names and directories. and only the content of the first template found will be added. 🎀

  • -m MSG, --message=MSG — issue title (and description). the first line is used as the issue title and any text after an empty line is used as the optional body. if this option is not used, the default GIT_EDITOR is opened so you can write one. ✍️
  • -l LABEL, --label=LABEL — attach LABEL to the issue (can be specified multiple times to set multiple labels).
  • -a USER, --assign=USER — assign a user to the issue. USER must be a valid GitHub login name.
  • -M ID, --milestone=ID — assign the milestone identified by the number ID to the issue.
  • --no-template — do not add the template content to the message.

🛠️ update ISSUE

similar to new but it updates an existing issue identified by ISSUE.

a convenient shortcut to close an issue is provided by the close subcommand. 😌

  • -m MSG, --message=MSG — new issue title (and description). the first line is used as the issue title and any text after an empty line is used as the optional body.
  • -t TITLE, --title=TITLE — new issue title.
  • -e, --edit-message — open the default GIT_EDITOR to edit the current title (and description) of the issue.
  • -o, --open — reopen the issue.
  • -c, --close — close the issue.
  • -l LABEL, --label=LABEL — if one or more labels are specified, they will replace the current issue labels. otherwise the labels are unchanged. if one of the labels is empty, the labels will be cleared (so you can use -l'' to clear the labels of an issue. 🧼
  • -a USER, --assign=USER — assign a user to the issue. USER must be a valid GitHub login name.
  • -M ID, --milestone=ID — assign the milestone identified by the number ID to the issue.

💬 comment ISSUE

add a new comment to an existing issue identified by ISSUE.

  • -m MSG, --message=MSG — comment to be added to the issue. if this option is not used, the default GIT_EDITOR is opened to write the comment.

🔒 close ISSUE

alias for update --close. (plus comment if --message or --edit-message is specified). closes the issue identified by ISSUE.

to be continued, bestie — there's more of this page and we are NOT stopping now 🦋

  • -m MSG, --message=MSG — drop a lil comment on the issue before you close it 💬
  • -e, --edit-message — opens your default GIT_EDITOR so you can write the comment that gets added to the issue right before closing. So polite of it.

🌈 pull 🌈

okay bestie, this one manages GitHub pull requests. And here's the tea: pull requests on GitHub are also issues, so most of the subcommands here are straight-up repeats from the issue command, just for convenience. The only ones that are actually different are list and new, plus attach and rebase get added to the party. 💅

✨ list ✨

Show a list of open pull requests. Iconic, simple, we love her.

  • --closed — show the closed pull requests instead. still valid, just retired 🪦

✨ show PULL [PULL ...] ✨

Just an alias for issue show. same energy, no notes.

✨ checkout PULL ... ✨

Checks out the remote branch (the head) of the pull request. What it does: first it fetches the head reference from the PR, then it calls the standard git checkout command. Any extra argument you pass gets handed to git checkout as-is, placed after the reference that was just fetched. 🫶

Heads up bestie: this creates a detached checkout by default 😭 use -b if you want to make a new branch based on the pull request. And pls go read git checkout help for the full details, iykyk.

✨ new [HEAD] ✨

Creates a brand new pull request. If you give it HEAD, that gets used as the branch (or git ref) where your changes live. If you don't, it uses the current branch. And if the branch you're using as head hasn't been pushed to your fork remote yet, it'll automatically push before creating the PR. no cap, it just does it for you ✨

The repository the pull request is issued from comes from the hub.forkrepo configuration, which defaults to hub.username/<hub.upstream project part>.

About the message: the content of the template files PULL_REQUEST_TEMPLATE or PULL_REQUEST_TEMPLATE.md gets added to the pull request message if either of those template files is found in the top-level directory of the project, the .github directory, or the .git directory. The lookup order matters, and it follows the order described above — for both the template file names and the directories. Only the content of the first template found gets added. first come, first served, periodt 💅

  • -m MSG, --message=MSG — the pull request title (and description). The first line becomes the pull request title, and any text after an empty line becomes the optional body. If you don't use this option, the default GIT_EDITOR opens. If the HEAD branch has a proper description (see git branch --edit-description), that description is used as the default message in the editor — and if it doesn't, the message of the last commit is used instead. 🎀
  • -l LABEL, --label=LABEL — attaches LABEL to the pull request (you can pass this multiple times to set multiple labels, go off 👑).
  • -a USER, --assign=USER — assigns a user to the pull request. USER must be a valid GitHub login name.
  • -M ID, --milestone=ID — assigns the milestone identified by the number ID to the pull request.
  • -b BASE, --base=BASE — the branch (or git ref) you want your changes pulled into. By default the tracking branch (the branch.<ref>.merge configuration variable) is used, or the configuration hub.pullbase if you're not tracking a remote branch. If none of those is present, an error gets displayed. 💀
  • -c NAME, --create-branch=NAME — creates a new remote branch (with the name NAME) as the real head for the pull request, instead of using the HEAD name passed as HEAD. Super useful when you wanna make a PR for a hot-fix you committed to your regular HEAD without making a branch first. 🧚
  • -f, --force-push — forces the push operations. Use with care! 🚨
  • -d, --draft — creates a draft pull request. Draft pull requests can't be merged, and code owners are not automatically requested to review draft pull requests.

✨ attach ISSUE [HEAD] ✨

Converts the issue identified by ISSUE into a pull request by attaching commits to it. You can optionally specify the branch (or git ref) where your changes are implemented with HEAD — otherwise the current branch is used. This subcommand is very similar to the new subcommand, so go peek at that one for more details.

Please note: you can only attach commits to issues if you have commit access to the repository, or if you're assigned to the issue. no shortcuts bestie 🙈
  • -m MSG, --message=MSG — adds a comment to the issue/new pull request.
  • -e, --edit-message — opens the default GIT_EDITOR to write a comment to be added to the issue/new pull request. The default message is taken from the --message option if present; otherwise the branch description or the first commit message is used, just like with the new subcommand.
  • -b BASE, --base=BASE — same as pull new, please see the details there. 🫡
  • -c NAME, --create-branch=NAME — creates a new remote branch (with the name NAME) as the real head for the pull request, instead of using the HEAD name passed as HEAD. Great for making a pull request for a hot-fix you committed to your regular HEAD without creating a branch first.
  • -f, --force-push — forces the push operations. Use with care! 🚨

✨ rebase PULL ✨

Closes a pull request identified by PULL by rebasing its base branch (the one specified in the pull request) instead of merging like GitHub's Merge Button™ would do. we're doing it the pretty way ✨

If the operation succeeds, a comment gets posted telling everyone the new HEAD commit of the branch that got rebased, and the pull request gets closed.

The type of URL used to fetch and push can be specified through the hub.pullurltype configuration variable (see CONFIGURATION for more details). Ideally your working copy stays exactly the same — if everything went OK, it does.

The operations this subcommand performs are roughly these:

  1. git stash
  2. git fetch pullhead
  3. git checkout -b tmp FETCH_HEAD
  4. git pull --rebase pullbase
  5. git push pullbase
  6. git checkout oldhead
  7. git branch -D tmp
  8. git stash pop

If hub.forcerebase is set to "true" (which is the default), --force gets passed to rebase — and no, don't confuse that with this command's own option --force-push, which forces the push. Otherwise (if it's "false") a regular rebase is performed. When the rebase is forced, all the commits in the pull request are re-committed, so the Committer and CommitterDate metadata gets updated in the commits — showing the person who performed the rebase and the time of the rebase instead of the original values, which is honestly more useful info. Side effect bestie: the hashes of the commits will change. 💀

If conflicts are found, the command gets interrupted, just like how git rebase would do it. You should either --abort the rebasing, --skip the conflicting commit, or resolve the conflict and --continue. When you use one of these actions, you have to omit the PULL argument.

  • -m MSG, --message=MSG — use this message for the comment instead of the default. Specify an empty message (-m'') to completely omit the comment. ✨
  • -e, --edit-message — opens the default GIT_EDITOR to write the comment.
  • --force-push — forces the push operations. Use with care! 🚨
  • -p, --pause — pauses the rebase right before the results get pushed and the issue gets merged. To resume the pull request rebasing (push the changes upstream and close the issue), just use the --continue action. This is especially useful for testing. 🧪
  • -u, --stash-include-untracked — passes the --include-untracked option to stash. If used, all untracked files are also stashed and then cleaned up with git clean, leaving the working directory in a very clean state — which avoids conflicts when checking out the pull request to rebase. immaculate vibes 🧼
  • -a, --stash-all — passes the --all option to stash. It's like --stash-include-untracked, but the ignored files get stashed and cleaned in addition to the untracked files, which completely removes the possibility of conflicts when checking out the pull request to rebase. maximum cleanliness, zero chaos 🫧
  • -D, --delete-branch — deletes the pull request branch if the rebase was successful. This is similar to pressing the "Delete Branch" Button (TM) in the web interface after merging. 🗑️

Actions:

  • --continue — Continue an ongoing rebase. slay, keep going 💅
  • --abort — Abort an ongoing rebase. not the vibe, but okay 😭
  • --skip — Skip current patch in an ongoing rebase and continue. keep it moving bestie 🏃‍♀️
  • update PULL — Alias for issue update. ✨
  • comment PULL — Alias for issue comment. 💬
  • close PULL — Alias for issue close. 🔒

🪝 HOOK SCRIPT 🪝

If the git configuration hub.hookscript is present, it will be used as a (shell) script to execute on certain events. Some data is passed as environment variables to the script. All events will set the HUB_HOOK environment variable with the name of the hook being executed. periodt.

NOTE: This is an experimental feature, so it is only enabled for one event only so far. 👀

Available hooks (events):

postclone

Executed after a clone command was done successfully. The script will be run with the freshly cloned repository directory as the current working directory, so the git configuration just done by the clone command is available (for example, git config hub.forkremote will get the fork remote). so handy bestie 🫶

The following extra environment variables are defined:

  • HUB_TRIANGULAR — will be set to true if the clone was done in triangular mode and to false otherwise. boolean queen
  • HUB_FETCHREMOTE — will be set to hub.forkremote if triangular was used and to hub.upstreamremote otherwise. remote vibes

This hook is useful to set some extra git configuration that should be enabled only when cloning a repository via this tool. For example, to prune the fork remote when it is updated, but only when triangular was used in the clone you can use:

git config --global hub.hookscript 'if test "$HUB_HOOK" = postclone && $HUB_TRIANGULAR ; then git config remote.fork.prune true; fi'

⚙️ CONFIGURATION ⚙️

This program use the git configuration facilities to get its configuration from. the way it just reads your git config These are the git config keys used:

  • hub.username — Your GitHub username. [default: current OS username] hey bestie
  • hub.oauthtoken — required This is the authorization token obtained via the setup command. Even when required, you shouldn't need to set this variable manually. Use the setup command instead. trust the process

If you don't want to store the token in plain text, you can also specify a command by prefixing a !. The output of that command will be used as the token. The command will be run with the default shell.

For example: oauthtoken = !password-manager ~/my.db get github-oauth-token.

  • hub.upstream — required Blessed repository used to get the issues from and make the pull requests to. The format is <owner>/<project>. This option can be automatically set by the clone command and is not really required by it or the setup command. auto-magic
  • hub.upstreamremote — Remote name for accessing the upstream repository [default: upstream]. up up and away
  • hub.forkrepo — Your blessed repository fork. The format is <owner>/<project>. Used to set the head for your pull requests. [default: <username>/(upstream <project> part)]. fork it
  • hub.forkremote — Remote name for accessing your fork. Used to push branches before creating a pull request. [default: fork]. push push
  • hub.pullbase — Default remote branch (or git reference) you want your changes pulled into when creating a pull request. [default: master]. the base of it all
  • hub.urltype — Type of URL to use when an URL from a GitHub API is needed (for example, when pull rebase is used). At the time of writing it could be ssh_url or clone_url for HTTP). See GitHub's API documentation[1] for more details or options. [default: ssh_url]. url vibes
  • hub.baseurl — GitHub's base URL to use to access the API. Set this when your GitHub API is in another location other than the default (Enterprise servers usually use https://host/api/v3). This will be prepended to all GitHub API calls and it has to be a full URL, not just something like "www.example.com/api/v3/". full URL only bestie
  • hub.forcerebase — If is set to "true", --force will be passed to rebase. If is set to "false" a regular rebase is performed. See the pull rebase command for details. [default: true]. force it
  • hub.triangular — Makes --triangular for clone if set to "true" (boolean value). See clone documentation for details. triangular slay
  • hub.hookscript — Script to run on certain events. Please have a look at HOOK SCRIPT for more details. hooks hooks hooks

[1] https://developer.github.com/v3/pulls/#get-a-single-pull-request

📁 FILES 📁

This program creates some temporary files in the .git directory during its operation. The contents of these files can be used for debugging/recovery purposes if necessary. save the receipts 🧾

  • HUB_EDITMSG — This file is used to take input from the user, e.g. issue comments, pull request title & description etc. If, after accepting user input, the command given by the user fails for some reason, then the entered text can still be retrieved from this file. your words are safe
  • HUB_PULL_REBASING — This file is used to store various metadata information related to a rebase operation (with the primary aim of being able to rollback the repository to its original state if the rebase fails or is interrupted due to conflicts). The sole presence of this file indicates that a rebase is in progress. rebase in progress, do not disturb 😤

🌈 VIM SYNTAX HIGHLIGHT 🌈

A VIM ftdetect plugin is provided, to enable it you have to follow some steps though. All you need to do is copy (or preferably make a symbolic link) the script to ~/.vim/ftdetect/githubmsg.vim:

mkdir -p ~/.vim/ftdetect
ln -s /usr/share/vim/addons/ftdetect/githubmsg.vim ~/.vim/ftdetect/
# or if you are copying from the sources:
# ln -s ftdetect.vim ~/.vim/ftdetect/githubmsg.vim

vim girlies rise 💅

👑 AUTHOR 👑

Leandro Lucarella <leandro.lucarella@dunnhumby.com> the icon, the legend 🫶

2013 dunnhumby Germany GmbH periodt 💖

and that's the tea bestie ☕ — this page is from the devel source/version, dated 2022-01-31, and it's the GIT-HUB(1) manual. now go slay some git 💅✨

📦 where this page comes from