Create a gist now

Instantly share code, notes, and snippets.

@dahlbyk /github.md
Last active Aug 21, 2017

What would you like to do?
Mastering GitHub

Mastering GitHub

GitHub is often used as a basic Git host, but its platform has so much more to offer. From simple and powerful issues and pull requests, to advanced features for power users and integrators, it’s a tool worth knowing well in its own right. This session will review everything you need to know to master collaboration with GitHub, from best practices for GitHub Issues and how it represents basic Git concepts, to hidden features and the tools enabling its developer ecosystem.

  • Git Hosting

    • Create Repository
    • Watch
    • Fork
      • Complete copy of the Repository
      • Can fork to user or organization
      • Part of parent project's "Network"
      • Can easily open Pull Requests to propose contributions
    • Code
      • Find file

        • Type t to activate
        • (Type ? to see all keyboard shortcuts)
      • Search

        • Search in code, commit messages, issues
        • Scope: repo, organization or global
      • Files

        {owner}/{repo}/tree/{commit-ish}/{path/to/tree}
        
      • Content

        {owner}/{repo}/blob/{commit-ish}/{path/to/blob}
        
      • Raw Download

        {owner}/{repo}/raw/{commit-ish}/{path/to/blob}
        
      • Blame

        {owner}/{repo}/blame/{commit-ish}/{path/to/blob}
        
      • History

        {owner}/{repo}/commits/{commit-ish}/{path/to/blob}
        {owner}/{repo}/commits/{commit-ish}/{path/to/tree}
        
        • Filter by query string (example)
          • author=dahlbyk
          • since=2015-12-25
          • until=2016-01-01
      • Single Commit

        {owner}/{repo}/commit/{commit-ish}
        {owner}/{repo}/commit/{commit-ish}.diff
        {owner}/{repo}/commit/{commit-ish}.patch
        
        • Containing branches and PRs
        • Can comment on lines and commit, but generally prefer comment in PR
        • Add ?w=1 to URL to ignore whitespace in diff (example)
      • Modification

        • New File / Upload, Edit File, Delete
        • Commit to current branch or create new branch for Pull Request
      • Hacking commit-ish

        • Previous commit: master~
        • 100 commits ago: master~100
        • Previous branch heads (reflog)
          • master@{1}
          • master@{yesterday}
          • master@{2016-01-01}
        • More at git help revisions
      • Linking

        • Type y to resolve commit-ish to canonical/permanent link
        • Click a line number to highlight and link to that line (#L123)
        • Hold Shift and click another line to highlight/link range (#L123-L456)
    • Branches
      • Can create and delete branches

      • General Git Tips

        • "Remote tracking branch" is what was on GitHub at last fetch/pull

          • refs/remotes/<remote>/<branch> AKA <remote>/<branch>
          • Configured with remote.<name>.fetch
            • +refs/heads/*:refs/remotes/origin/*
            • GitHub PR heads: +refs/pull/*/head:refs/remotes/origin/pr/*
          • Deleted branches' tracking refs are not automatically deleted
            • git remote prune origin
            • git fetch --prune
            • Always want to prune?
              • git config remote.<name>.prune true
              • git config fetch.prune true
        • Start work on a remote branch

          > git checkout -t origin/my-branch
          On branch my-branch
          Your branch is up-to-date with 'origin/my-branch'.
          nothing to commit, working tree clean
          
          • Or, if <branch> exists on only one remote: git checkout <branch>

          • Tracking lives in config

            git config branch.master.remote         # origin
            git config branch.master.merge          # refs/heads/master
            
        • To set up tracking when pushing new branch

          > git push -u origin HEAD
          Total 0 (delta 0), reused 0 (delta 0)
          To https://github.com/dahlbyk/my-repo.git
          * [new branch]      HEAD -> my-branch
          Branch my-branch set up to track remote branch my-branch from origin.
          
          • Using HEAD pushes current branch to branch of same name
            • git config --global alias.pc "push -u origin HEAD"
          • Can also use branch name to push any branch to branch of same name
          • Can also use source:destination to push to branch of different name
            • git push origin my-branch:my-awesome-branch
          • Have a convention to prefix branches with username?
            • git config alias.pc = !git push -u origin HEAD:dahlbyk/$(git symbolic-ref --short HEAD)
          • To delete branch, source is empty: git push origin :my-branch
      • Default Branch

        • Shown when repo is opened
        • Set as <remote>/HEAD on git clone
          • Handy for global aliases to not assume master
          • git config --global alias.new "log --oneline --decorate --reverse origin.."
      • Protected Branches

        • Disables force-pushes to this branch and prevents it from being deleted.
        • (optional) Require pull request reviews before merging
        • (optional) Require status checks to pass before merging
      • Compare

        {owner}/{repo}/compare/{revision range}
        {owner}/{repo}/compare/{revision range}.diff
        {owner}/{repo}/compare/{revision range}.patch
        
        • revision range can either be a range (<base>...<head>)…
        • …or a commit-ish, equivalent to <default>...<head>
        • If <base> and <head> are both branches, can open a Pull Request
        • <base> and <head> can include a fork prefix, e.g. dahlbyk:master...coridrew:tfs
  • Issues

    • GitHub-Flavored Markdown
      • Syntax highlighting
      • Task lists
      • Auto-linking
        • Commit SHAs (deadbeef or owner/repo@deadbeef)
        • Issue/PR references (#1, repo#2, owner/repo#3)
        • Parsing of GitHub URLs (e.g. "#1 (comment)")
    • Issue/PR mentions in issues/PRs/commits show up as references
      • Build a graph of inter-related issues
    • Milestones (due date, completion %)
    • Labels
    • Assignees
      • New: multiple assignees
  • Pull Requests

    {owner}/{repo}/pull/{number}
    {owner}/{repo}/pull/{number}.diff
    {owner}/{repo}/pull/{number}.patch
    
    • Formerly "an issue attached to a branch"
      • Could even use API to convert issue to PR…but you shouldn't
    • Commits
      • Used to link away to raw commit
        • comments on commit/lines didn't work well; lost after rebase
      • Now commits keep PR context, comments work much better
    • Changes
      • Comment per line
      • Standalone or collected in a Review
      • Can limit to changes since last review, or specific commit
    • Deployments
    • Checks
      • CI
      • Linting
      • Review Approval
  • Projects

    • Add issues or notes to columns
    • No workflow (e.g. Closed move to last column)
    • Also check out HuBoard
  • Repo Settings

  • For Developers

    • API v3
    • GraphQL Early Access
      • Limited scope, but used internally for new features (e.g. Projects)
    • Integrations Early Access
      • Different from integrations directory
      • Primarily targeting "non-user" users, e.g. no more CI admin user
  • Gist

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment