Skip to content
This repository has been archived by the owner on Feb 1, 2020. It is now read-only.

Git FAQ

Jump to bottom
dwightguth edited this page Apr 9, 2014 · 10 revisions

This page is broken down by use cases. Look for the heading that describes what you are trying to do, and follow the instructions.

Create a fork (do this once)

  1. Go to: https://github.com/kframework/k
  2. Click the "Fork" button in the upper right, then select your personal account.
  3. In your git console, run git clone with the argument in the right sidebar on github. For example, Dwight runs git clone https://github.com/dwightguth/k.git. If you normally connect to git via SSH (e.g. because you want to specify an SSH key), you would use the SSH clone URL: git clone [email protected]:dwightguth/k.git.

Create a new clean branch to contain your change

In order to simplify the process of manipulating changes, it is often very convenient to have a local branch named "master" which tracks "origin" and contains no local changes. This allows you to easily create new clean branches by running the command git checkout -b <branch_name> master. These branches then contain your changes so that the "master" branch remains unmodified and in sync with the main kframework repository.

To create a new feature branch to commit your changes to, run the above command. However, if you already have made changes to your local "master" branch, it is advisable to move these changes onto a feature branch. To do this:

git checkout -b <branch_name> master # this creates a branch containing your changes so they are not lost when you rebase master
git checkout master # move back to master branch so that the following command works correctly
git reset --hard upstream/master # reset working copy and all local commits to the upstream/master which is clean

By making your changes only on branches of your local "master" branch, you simplify the process of merging, rebasing, moving changes between branches, etc.

Create a pull request

  1. Log into github and click "Pull request" next to the line that says "This branch is commits ahead and commits behind master".
  2. If you are pulling into a branch other than master, make sure you click "Edit" at the top and then select that branch where it says "Base".
  3. Make sure you are submitting the correct change, type up a description for it, then submit it. This automatically emails everyone watching the K framework repository except yourself.
  4. If you need a particular user to review your change, you should tag their Github user ID in the pull request description. For example to ask me to review something you might say "@dwightguth Please review."
  5. At this point it becomes the responsibility of reviewers to comment on your change and either approve it or request modifications. They can do this by accessing the pull request online and commenting on the change or on specific lines of code. If they request changes, you can update the pull request simply by pushing further changes on the same branch to your fork. Once the pull request is approved, you are free to click the "Merge pull request" button on the bottom of the pull request screen to automatically merge and close the pull request.

Continuing to work after submitting the pull request

  1. Note that any push made to the same branch after the pull request is opened but before it is closed will add that commit to the pull request. To continue working on a different change during that time period, you must work on a branch.
  2. Create a short-term feature branch in your fork by running the command git branch <branch_name> <commit_id_to_branch_from>. For example to create a branch named "foo" from the commit immediately prior to the most recent, you might run git branch foo HEAD^. For information on how to specify commits, see git help revisions
  3. Switch to the new branch by running git checkout <branch_name>.
  4. Start making your new change. When it comes time to perform a pull request, push the changes upstream to the branch you created by running git push origin <branch_name>.
  5. Proceed from section "Create the pull request"

Syncing your fork with the upstream repository

  1. (do this once) run git remote add upstream [email protected]:kframework/k.git (or use HTTPS if you prefer). This adds a remote repository to your local repository for the kframework/k repository.
  2. Run git pull --rebase upstream <branch_name> to sync a particular branch with the main repository. Do this if your branch is behind the master repository.
Clone this wiki locally