Resources

GitHub Default Files

Different from template repositories, GitHub also supports a very special type of repo - the .github repo.

Certain files that you place in this repository (after you create it at /your_name_or_org/.github), will be used as the default (e.g. fallback) file in all your repositories, if that same file is missing within the specific repo.

There is a full list of supported default files, but some specific examples are:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• Issue and PR templates
  • Create under .github/ISSUE_TEMPLATE, follow directions
  • Given the name of the repo, path actually looks like .github/.github/..., see below for examples

If you are looking for some examples of what this repo looks like:

• github/.github (how meta 😁)
• creativecommons/.github
  • This is a very thorough use-case; they also use the /.github subfolder for issue templates

Your Github Profile

You can now customize your Github profile by creating a repo with the same name as your username, and editing README.md with the content you want. For more details, follow this handy guide.

Here is my profile 👨‍💻 😊

Tips and Tricks

Misc Tips and Tricks

• How to tell which release a PR ended up in
  • One way is through the GitHub online UI. If you look at a specific commit, there should be a UI section in the top header that you can expand to show all git tags that the commit was included under
• Get the size of a repo before cloning / forking /etc.
  • There is an API endpoint you can use to get repo info, including size. No login / creds required for public repos!
    • https://api.github.com/repos/{owner}/{repoName}
    • You can use a browser, cURL, or your fetcher of choice, then look for .size, which is in KB.
• Get when a file was last modified, via Github API
  • See StackOverflow answer
  • Example implementation: only trigger fresh build if Github source file has changed.
• Where to find issues:
  • Where to find all your subscribed issues: nofications/subscriptions
  • Where to find all your assigned issues: issues/assigned
• To center an image in a GitHub README, wrap the image tag, like so: <p align="center"><img src="..."></p>
• Why are my issues not being closed when using the magic keywords (such as closes) in commit messages / PR text?
  • Make sure the number immediately follows the keyword, as per examples.
  • closes issue #1 will not work, but closes #1 issue will.
  • Although one PR can link to and auto-close multiple issues, they have to be linked directly via PR. One issue cannot auto-close another issue.
• You can use date references in some GitHub URLs, e.g. github.com/{USER}/{REPO}/tree/{BASE_REF}@{DATE_REF}
• How to get the raw URL for a file?
  • Option: Add raw=true as query param

Searching Github

🚀 Check out the new Code Search feature!

Docs:

• "Understanding the Search Syntax".
• Official cheat sheet

Tips:

• You can search across all your own code, by filtering by your own username, with user:{your username}
• You need to be logged in for many of the advanced search filters and code search
• Sometimes languages don't show up in the language selector, but are still "filterable" via query string manipulation
• You can find issues that someone commented on with is:issue commenter:{username} (S/O)

Badges

Ultimate one-stop-shop for finding badges - shields.io

Some of my favorite badges / most used:

• GitHub Actions
  • URL: https://github.com/{USER}/{REPO}/actions/workflows/{WORKFLOW_FILENAME}/badge.svg
  • MD: [![CI Badge](https://github.com/{USER}/{REPO}/actions/workflows/{WORKFLOW_FILENAME}/badge.svg)](https://github.com/{USER}/{REPO}/actions/workflows/{WORKFLOW_FILENAME})
  • Also, see *"Github Actions and Workflows" for alternative formats
• Glitch Badges
  • From your project editor, you can find remix links and images by using Share -> Share Buttons
  • One official remix SVG URL is https://cdn.gomix.com/f3620a78-0ad3-4f81-a271-c8a4faa20f86%2Fremix-button.svg
  • For more details:
    • remix.glitch.me
    • github-import.glitch.me
• CodeCov:
  • URL: https://codecov.io/gh/{USER}/{REPO}/branch/{BRANCH}/graph/badge.svg
  • MD: [![Code Coverage Badge](https://codecov.io/gh/{USER}/{REPO}/branch/{BRANCH}/graph/badge.svg)](https://codecov.io/gh/{USER}/{REPO}/branch/{BRANCH})
• NPM:
  • MD: [![NPM Badge](https://img.shields.io/npm/v/{PKG_NAME})](https://www.npmjs.com/package/{PKG_NAME})
• Git tag version:
  • ![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/{USER}/{REPO})
• Netlify deploys
  • URL: https://api.netlify.com/api/v1/badges/{PROJECT_UUID}/deploy-status
  • Go to your settings page to find the ID & URL - e.g. https://app.netlify.com/sites/{PROJECT_NAME}/settings/general#status-badges
• Github repo badges (for if you are deploying markdown elsewhere, or just want GH stats)
  • Last commit:
    • MD: [![Last Github Commit](https://img.shields.io/github/last-commit/{USER}/{REPO})](https://github.com/{USER}/{REPO}/)
• Git SHA
  • Checkout my blog post: "Git SHA Badges for Deploys"
  • If you just need the latest commit on Github, you can use:
    • https://img.shields.io/badge/dynamic/json?color={COLOR}&label={LABEL_STRING}&query=object.sha&url=https://api.github.com/repos/{USER}/{REPO}/git/refs/heads/main
    • This is explained in greater detail in the above linked blog post

Don't forget; you can link your badge to a webpage! In markdown, use [![Badge Alt Text](Badge_URL)](Link on badge click)

PRs (Pull-Requests)

Stacked PRs

A Stacked PR (Pull Request) is typically the term for a pull-request from a feature branch into another feature branch, where the destination feature branch is typically awaiting a PR review to be completed and merged into the trunk.

For example:

Feature B (Stacked PR)
 |
 |----> Feature A (Regular PR) (awaiting approval)
         |
         |---------> Main / Trunk

Sometimes this can become a necessity, if the main PR has become blocked, but you still need to add code to that branch.

Not only are stacked PRs sometimes a necessary part of the flow for software development, but some platforms even have certain features baked in that improve the stacked PR experience. For example, on GitHub, if the intermediate branch gets merged, the base of the secondary PR will auto-update to point at the new base (which should be your main branch now).

However, in general Stacked PRs are usually something to avoid, as it might not be guaranteed that the intermediate PR gets eventual approval, which would mean that your tertiary PRs could be building on code that is ultimately rejected.

Batching Responses

For the reviewer of a PR, there is a very convenient batching / draft feature, which lets you build up feedback and requested changes, before posting it in one go. That lets the reviewer go at their own speed and place comments in different spots, while avoiding pinging the PR author on every edit.

Unfortunately, on the other side of the equation, there are fewer tools for the author of the PR to batch their responses to the review (i.e. a review of the review), at least that I'm aware of.

The only workaround I know is that you can use the Files Changed tab to start a new review, in which your replies will stay as "pending" / draft, until you submit the review. The downside is that your review (the review of the review) appears rather oddly in the GitHub UI once submitted, since it is almost treated as an independent review, rather than a set of responses.

Special Diffing Views

There are some special diff / comparison URLs for Github - check out "Things you didn't know you could diff in Github" and GitHub - View and Compare Commits.

Dealing with PRs Locally - Method A

The best way, although maybe not the fastest, to deal with a PR locally is to set up a new local branch that tracks to the PR's branch - this is not so straightforward if the PR is for a forked repo.

Having a tracked branch will also allow you to push commits to the PR author's branch, assuming that they left the box checked that says "allow edits from maintainers".

In the case that the PR is to merge a branch from a fork (as is common with open-source work), here is what you need to do:

1. Add the forked repo as a remote
   • git remote add {alias_for_fork} {fork_full_repo_url.git}
2. Get the data from the new remote
   • git fetch {alias_for_fork}
     • OR
   • git fetch --all
3. Now, you can either checkout their branch directly, or make a branch to track their branch:
   • Directly checkout: git checkout {alias_for_fork}/{pr_branch_name}
   • Via tracking branch: git checkout -b {mirror_branch_name} {alias_for_fork}/{pr_branch_name}
     • Example: git checkout -b fred-master fred/master

An alternative order for the above steps is to start with checking out a new PR branch based off your trunk, then pulling the remote onto it:

git checkout -b {pr_branch_name} {trunk_branch_name}
git pull {FORKED_PR_REPO.git} {trunk_branch_name}

the above approach is what Github recommends when you click the "view command line instructions" link in a PR.

If you want to add a commit to their PR branch, simply add the new commit to your tracking branch, and then:

• If you checked the branch out directly, simply use git push
• If you are using a "mirror" branch, use git push {alias_for_fork} HEAD:{pr_branch_name}
  • The git CLI should automatically prompt you to do this if you forget and try to just use push without options (it will throw a fatal: the upstream branch does not match the name of your current branch)

Dealing with PRs locally - Method B

A faster way to interact with and git checkout a PR locally, even before any of it is merged, by using this:

git fetch origin pull/{PR_NUMBER}/head:{LOCAL_BRANCH_TO_CREATE}

For example:

git fetch origin pull/4/head:pr-4

Just replace the PR # with the one you want!

For updating your local branch after the PR has been updated, you can use git pull origin pull/{PR_NUMBER}/head

For details, see this breakdown on how the command works

Keyboard Shortcuts!

Github Actions and Workflows

Moved here