GitHub Cheat Sheet - autokey/autokey GitHub Wiki

Contents

About

This page provides the steps for doing some of the tasks you may want to do on GitHub when contributing to the AutoKey project. The sections are alphabetized and don't necessarily present the entries in the order in which you'd use them.

Add a link to a URL on your repository's main GitHub page

To put a link to your official documentation or any other website that you like in the right panel of your repository's main GitHub page:

  1. Go to your repository's main page.
  2. Click the gear next to About in the right panel.
  3. Paste the URL into the Website box.
  4. Save the change.

Archive or unarchive a GitHub repository

Archive a repository:

  1. Go to the main page of the repository.
  2. Click the Settings in the menu.
  3. Scroll down to the Danger Zone section.
  4. Click Archive this repository.
  5. Read the warnings.
  6. Type the name of the repository.
  7. Click I understand the consequences, archive this repository.

Unarchive a repository:

  1. Go to the main page of the repository.
  2. Click the Settings in the menu.
  3. Scroll down to the Danger Zone section.
  4. Click Unarchive this repository.
  5. Read the warnings.
  6. Type the name of the repository.
  7. Click I understand the consequences, unarchive this repository.

Basic GitHub Workflow

These steps take you through the basic workflow for using GitHub in your browser to contribute to the AutoKey project in a beginner-friendly way.

  1. Fork a remote repository:
    1. Go to the repository's main page.
    2. Click the Fork button in the top right corner.
    3. Choose an owner for the fork if you like (it will be you by default).
    4. Change the name of the fork if you like (it will be the original repository's name by default).
    5. Change the description if you like (it will be the original repository's description by default).
    6. Uncheck the Copy the master branch only box (this is important).
    7. Click the Create fork button. Note that once the forking process is complete, you'll automatically be at the main page of your new forked repository.
  2. Open the branch you'd like to work on.
  3. Create a new branch off of that branch with a name that lets you know what kind of change you're about to make. Note that this will be a temporary branch that's for your use only and won't be copied to the remote repository that you forked from.
  4. Make one or more changes to files inside the new branch with one of these methods:
    • Use the GitHub editor to make the changes, committing each one with a comment describing what you did.
    • Use the command line to clone your fork, make the changes, and push them to your fork.
  5. Update the CHANGELOG.rst file to note the change(s).
  6. Start a pull request with any one of these methods:
    • Click the Compare & pull request button above the file list.
    • Click the link in the note above the file list that tells you that this branch is ahead of the branch your changes will be made in.
    • Click Pull requests in the top menu and then click the Compare and pull request button.
    • Click Pull requests in the top menu and then click the New pull request button.
  7. Check the information in the grey section at the top to make sure that:
    • the base repository is the remote repository that you forked
    • the base is the remote branch that you want to change
    • the head repository is your fork
    • the head or compare is the branch that contains your change(s)
  8. Scroll down to review the change(s) you made to the file(s).
  9. When you're satisfied with the settings and your changes, click the Create pull request button.
  10. Wait for the tests to complete and verify that you have an Able to merge message from GitHub.
  11. Type a meaningful title for the pull request into the top text box to give the remote repository's maintainer a quick idea of the reason for this pull request.
  12. Optionally, type a detailed comment into the Write text box, letting the remote repository's maintainer know more about the change(s) that you've made.
  13. Click the Create pull request button.
  14. You'll be notified by email once the remote repository's maintainer has merged the pull request into the remote repository. You can then delete the temporary branch you had created in your fork in step 3 above or delete the entire fork:
    1. Go to the remote repository's main page.
    2. Click the Pull requests entry in the menu.
    3. Click Closed in the heading above the list of pull requests on that page.
    4. Click on the name of your pull request.
    5. Scroll down to the Pull request successfully merged and closed section at the bottom.
    6. Click the Delete branch button in that section to delete the branch and keep the forked repository or, if you no longer want the forked repository, click the settings link in that section.
    7. The next time you open the affected branch in your fork, GitHub will notify you at the top of the file listing that your branch is out-of-date. This is because the changes you made in your temporary branch have now been made in the base branch you chose in the remote repository and they now need to be made in your fork so the two repositories can be identical. To synchronize them:
      1. Click the Sync fork button to the right of that message.
      2. Click the Update branch button.

As an example, if you created the foo branch off of the develop branch in your fork, changed the contents of its readme.txt file, did a pull request, chose develop as the base, and chose foo as the head, the readme.txt file in the remote repository's develop branch will be the file that changes. The remote repository will not get a copy of your foo branch and you'll be able to delete the foo branch once the pull request is merged into the remote repository.

If, instead of following the above steps and editing a file in your fork, you attempt to edit a file in a repository that you don't have push rights to (the AutoKey repository), when you commit the change(s), GitHub will automatically offer to create a branch with the default name of patch-1 (or patch-2, etc., depending on whether other patch branches exist). You can edit the branch name if you like. That branch gets created in the remote repository you don't have push rights to (in this case, the AutoKey repository) when you do a pull request and it's accepted, and it's the branch that's used as the base for the pull request. Your fork will then get a copy of that branch the next time you sync the branches. If you then view the branches in your fork, you'll see that you own that branch. Once the pull request is accepted, you can delete the branch from your fork and it will be automatically deleted from the remote repository that you don't have push access to without a pull request.

Create a release

Tagged releases merged onto beta or master will automatically be built.

Create an interactive GitHub issue template form

The standard bug report on GitHub is ordinary Markdown. You can create a YAML issue template form that's interactive instead.

  1. Create the .github/ISSUE_TEMPLATE/bug.yaml file while you're in the main branch of your repository. That will create the .github folder inside of the main branch, the ISSUE_TEMPLATE folder inside of that one, and the bug.yaml file inside of that one.
  2. Populate the bug.yaml file with your YAML code.
  3. Commit the change.

If you'd like to prevent blank issues from being used and ensure that your users will use your issue template:

  1. Create the config.yml file inside of the /.github/ISSUE_TEMPLATE folder.

  2. Paste or type this line into it:

    blank_issues_enabled: false

  3. Save the file.

  4. Commit the change.

Create or add a folder on GitHub

GitHub offers a way to create a folder, but you cannot create an empty folder, so the idea is that you create a file and specify a folder for it to go into as part of the creation process.

  1. Open the branch you'd like to create a folder in.
  2. Click the "Add file" button.
  3. Type a new folder name followed by / followed by a new file name into the text box. Note that if you regret the folder name you just typed in, typing .. followed by / will remove it or you can use the backspace key to edit the parent folder's name.
  4. Click the "Commit new file" button to create the folder and file and enter the folder.

Note that you can apparently drag a folder with at least one item inside of it from your computer into the GitHub repository page, but I haven't tested that.

Create or manage GitHub milestones

You can create and manage milestones (goals) for your GitHub project:

  1. Open your GitHub repository's main page.
  2. Click Issues in the menu.
  3. Click the Milestones tab next to the New issue button.

Create or manage GitHub saved replies

GitHub's saved replies offer you a way to store snippets of boilerplate text and use them in any comment box on GitHub.

  1. Click on your GitHub profile image.
  2. Click Settings in the drop-down menu.
  3. Click Saved replies in the Code, planning, and automation section in the left pane.
  4. Type a title for your saved reply into the Saved reply title text box.
  5. Type a reply into the Write text box.
  6. Preview your reply in the Preview tab and go back to the Write tab to edit it if you'd like to make changes.
  7. Click the Add saved reply button to store the saved reply.

Now, you'll be able to click the little curved arrow above any comment field on GitHub and select that reply by its title in the drop-down list that opens.

Delete a repository from GitHub

Once your code has been accepted and merged into a project, you can delete the fork. Deleting a fork will have no effect on the project it was forked from.

  1. Go to your local repository's (the fork's) main page.
  2. Click on Settings in the top menu.
  3. Scroll to the bottom of the page to the Danger Zone section.
  4. Click the Delete this repository button.
  5. Type in your GitHub username and repository's name at the prompt.
  6. Click on the I understand the consequences, delete this repository button.

Do a pull request on GitHub

See the Basic GitHub Workflow section above.

Enable the GitHub issue tracker in your repository

  1. Log into your GitHub account.
  2. Select your repository.
  3. Open the Settings tab.
  4. Open the Options tab.
  5. Scroll down to the Features section.
  6. Activate the issue tracker by putting a check-mark in the Issues box.

Fork a GitHub repository

  1. Go to the repository's main page.
  2. Click the Fork button in the top right corner.
  3. Choose an owner for the fork if you like (it will be you by default).
  4. Change the name of the fork if you like (it will be the original repository's name by default).
  5. Change the description if you like (it will be the original repository's description by default).
  6. Uncheck the Copy the master branch only box (this is important).
  7. Click the Create fork button.

Pin a gist or repository to your GitHub home page

If you'd like quick access to one of your gists or repositories from now on:

  1. Go to your GitHub home page.
  2. Click Customize your pins in the right center of your home page.
  3. Put a check-mark in the box next to the gist or repository you'd like to pin.
  4. Click the Save pins button.

Revert a commit

This must be done with Git on the command line.

Revert a pull request

  1. Open your repository on GitHub.
  2. Click the Pull requests tab.
  3. Click the pull request that you'd like to revert.
  4. Click the Revert button. Note that this will create a new pull request that reverts the changes.
  5. Submit the resulting pull request.

Search a GitHub repository's wiki for pages containing the specified string

All of these examples are searching for foo in the wiki and you can change that to whatever you'd like to search for:

Search a repository's wiki for pages updated within the specified date range

To search by last-updated date, the updated qualifier matches wiki pages that were last updated within the specified date range. When you search for a date, you can use greater than, less than, and range qualifiers to further filter results. For more information, see the Understanding|the search syntax page. Some example searches:

  • Match wiki pages containing the word "foo" that were last updated after 2016-01-01: foo updated:>2016-01-01
  • Match wiki pages that were last updated before 2016-01-01: repo:autokey/autokey updated:<2016-01-01
  • Match wiki pages that were last updated after 2016-01-01: repo:autokey/autokey updated:>2016-01-01
  • Match wiki pages that were last updated on or before 2016-01-01: repo:autokey/autokey updated:<=2016-01-01
  • Match wiki pages that were last updated on or after 2016-01-01: repo:autokey/autokey updated:>=2016-01-01

See also