DP Code Development Using git

From DPWiki
(Redirected from User:Cpeel/git conversion)
Jump to navigation Jump to search

There are multiple ways to use git to develop. Most of the repos in the Distributed Proofreaders organization use the "fork, branch, develop, merge" model, where developers are expected to:

  1. fork the main repository
  2. create a development branch off master
  3. develop code on the branch
  4. generate a merge/pull request when ready to merge

This page highlights some common developer activities regardless of the repo. It does so assuming you are working from the command line directly. There are many excellent tools and IDEs that will manage much of this for you, but the overall process is the same. See DP Code Development Using Github Desktop for a parallel description to this page, but using GitHub Desktop for Windows or macOS instead of git commands.

See the DP Code Development Using git: dproofreaders for more detailed instructions for that repo.

Initial repository set up

To get started with a git repo for DP, you have to first create a fork of the code repository under your GitHub user ID. You only need to do this once ever.

On Windows, you will probably first need to install Git Bash (command window for git commands) from the Git for Windows site.

  1. If you haven't yet, create a GitHub account.
  2. Log into your GitHub account.
  3. Add your public SSH keys to your GitHub account if you haven't done so already. Be sure that the matching private key is installed on the system from which you will be running the git commands.
  4. Go to the DP repo you want to work on and fork the repository by clicking Fork in the upper right
    • Click on your github username as the location to create the fork.
  5. After a few seconds, this will take you to your forked copy of the DP repo under your username

This will create a fork of the code under your GitHub userid, eg: https://github.com/cpeel/dproofreaders

Cloning the repo

After the repository is set up, you need to set up the code on your workstation. You only need to do this once per development system.

  1. On your workstation (e.g., your home computer), open a shell/terminal window.
  2. If this is your first time using git on this system, start by configuring git with your name and email address. Note that these values will be visible publicly:
    • git config --global user.name "<NAME>"
    • git config --global user.email "<EMAIL>"
      • Consider using <USERNAME>@users.noreply.github.com if you don't want your personal email address publicly accessible.
  3. Go to the directory/folder in which you want to hold your source code. A ~/git/ directory is common but can be anywhere.
  4. In a browser, go to your fork of the code in GitHub.
  5. Click the green "Clone or download" button and copy the URL it lists there and run the following in the same shell from step 1
    git clone $URL
  6. Because the command tries to establish an SSH connection to GitHub, you may get some SSH warnings, e.g. "The authenticity of host 'git@github.com' can't be established", and your OS may ask you to supply the password associated with the public key that GitHub has for you.
  7. Depending on your connection speed, the command will take 15 seconds or so to pull down a clone of your repository. When done, it will have created a sub-directory with the name of the repo you cloned, e.g. dproofreaders.
  8. Right now your local repo has a remote called origin that points to your fork. We will want to add a new remote called upstream so you can refresh your fork. To get the URL for the upstream repo, go to the repo you forked, click the green "Clone or download" button, and copy the HTTPS URL it lists. cd into the repo directory, then run the following command to add the primary repository as an 'upstream remote' for your local clone:
    git remote add upstream <HTTPS URL to upstream repo>

Developing

Note that all of these steps only make changes in your fork, not the main repository, so feel free to play with these commands all you want -- you can't break anything.

  1. Create a branch to capture the work you are doing, use a branch name that is descriptive but concise
    git branch <branchname>
    git checkout <branchname>
  2. Make any changes you want using a standard git workflow:
    1. Make code changes and test them
    2. Group logical changes into one commit via:
      git add file1 file2 file3
      git add file4
      git commit
      • In the commit message, the first line should be 50 characters or fewer and summarize the commit; then a blank line; then lines of 72 characters or fewer with additional details.
    3. Repeat 1 & 2 as needed
  3. To push your changes up to GitHub for others to see:
    git push origin <branchname>

Merging your changes

After you have code you want merged into the main DP repository, open a pull request from your fork on GitHub so devs can review your code.

  1. Go to your fork in GitHub (eg: https://github.com/cpeel/dproofreaders)
  2. Click "New pull request" to generate a pull request
  3. Select the branch you want to merge from the 'compare:' drop-down on the right
    • This will show you the commits that will be included in the pull request and the changes in those files
  4. Click "Create pull request"
    • The Title should contain a short summary of what your branch has in it
    • The Comment field should contain a more lengthy description of what your changes do.
  5. Click "Create pull request" to finalize the pull request

If, as a result of subsequent code review, you add some commits to your branch, and push them to your fork on GitHub, your pull request will be updated automatically.

Refreshing your fork

The following walks you through refreshing the code in your fork to include updates since you forked. You will probably always want to update the master branch in your repo. If you have one or more code branches you're working on, you can update those too. These steps are not required to open a merge request.

  1. To refresh your fork from the project master on GitHub (ie: the upstream repo):
    git checkout master
    git fetch upstream
    git rebase upstream/master
  2. To refresh a code branch (if you have one):
    git checkout <branchname>
    git rebase master
  3. And then push them back up with:
    git push origin master
    git push origin <branchname>
    • If you've pushed your branch to origin and then rebase it (which is all OK), you've altered the commit stream and the push will fail with the message:
      To prevent you from losing history, non-fast-forward updates were rejected
      Merge the remote changes (e.g. 'git pull') before pushing again.

      If this happens, you can force the push such that the local changes overwrite the changes in origin:
      git push origin --force <branchname>

Reviewing code

There are multiple ways to review code, either that is just in another user's fork or that they've submitted in a merge request. Different people will want to do it differently, but here are some ideas:

To access the other user's code:

  • You can view the individual commits and the entire tree via the GitHub web UI.
  • Set up the other user's repo as a remote in your local repo, then fetch their repo, check out their branch, and review the code:
    git remote add user_blah https://github.com/cpeel/dproofreaders.git
    git fetch user_blah
    git checkout user_blah/branchname
  • Clone the other user's repo as an entirely new local repo, then check out their branch and review the code:
    git clone https://github.com/cpeel/dproofreaders.git
    git checkout branchname

If you opt to have the code locally, the following are useful git commands after you have checked out their branch:

  • Review the commit log for the current branch that is checked out:
    git log
  • Review the commit log for an arbitrary branch:
    git log <branchname>
  • View the diff between two commits:
    git diff <hash1> <hash2>

git Training Resources

Retrieved from "https://www.pgdp.net/w/index.php?title=DP_Code_Development_Using_git&oldid=127332"