SE-2800 Software Engineering Process

Dr. Mark Sebern -- Winter quarter 2013-2014


Lab 2

Revised: 8 January 2014

Acknowledgment

This lab was developed by Dr. Rob Hasker; all errors in its adaptation are the responsibility of the instructor.

Overview

See Dr. Hasker's lab 2 description

Procedure

This is a pretty detailed sequence of operations, and it is possible that there are some errors in the instructions, or unusual situations that you may get yourself into. If you have any problems, ask the instructor for help right away. Also, please report any corrections or clarifications that should be made to the lab write-up.

Setting up SSH

The first step is to set up SSH keys for use with BitBucket on Windows.

BitBucket has directions for using the ssh-keygen tool in Git Bash, but that set of directions has a lot of steps to it. The steps given here use PuTTY-based tools, PuTTYgen (key generator) and Pageant (key agent).

  1. Download the Windows installer for PuTTY from www.chiark.greenend.org.uk/~sgtatham/putty/download.html.
  2. Execute the installer.
  3. Run PuTTYgen, from All Programs->PuTTY->PuTTgen in the start menu.
  4. In PuTTYgen, make sure the type of key is set to SSH-2 RSA (at the bottom of the screen), and click on the Generate button.
  5. Move the mouse around as directed by PuTTYgen, to generate random data to be used in generating your key pair.
  6. Enter a key passphrase. You should only have to type this whenever you reboot your computer, so it should be a reasonably long phrase.
  7. Click the Save public key button and save the key in a file with a .pub extension. The extension doesn't actually matter, but using something consistent like .pub allows you to identify the file later.
  8. Click the Save private key button and save the key in a file with a .ppk extension. Although the keys are protected by your passphrase, it's better to keep this file under your control. Store it in a safe place.
  9. Do NOT exit PuTTYgen yet.
  10. In BitBucket (on the web), select Manage account from the "avatar" menu in the upper right corner of your browser.
  11. Click on SSH keys in the list on the left side and then click on the Add key button.
  12. Enter a convenient label such as "PuTTYgen key 2014/01/07". This label identifies your key in case you later wish to revoke it.
  13. Returning to PuTTYgen, select the text in the box just below the label that says Public key for pasting into OpenSSH authorized_keys file. Instead of using the authorized_keys file, copy and paste all this text into the BitBucket web page where it says Paste your key here.... Then click on the Add key button.
  14. In Windows, start the Pageant key agent program. No window will open, but an icon of a computer with a hat on it will show up in your system tray; right click on that icon and select Add Key.
  15. Browse to your .ppk (private key) file, open it, and enter the passphrase. Since BitBucket has a copy of your public key, you can now exchange files with BitBucket, without entering your password (as long as Pageant is running).

You should now be ready to install Git and access BitBucket.

Setting up the Windows Git client

Before installing Git, you need to create a site profile in PuTTY, or Git will not install correctly. Why? It's magic. (Actually, it's a defect in the Git installer code that would otherwise make it think PuTTY was not available.)

  1. Run PuTTY
  2. Enter "www.msoe.edu" in the Host Name field. (This is kind of arbitrary, but go with us on this one . . .)
  3. Enter "msoe" in the Saved Sessions name field.
  4. Click on the Save button.
  5. Exit PuTTY.

Next, install the Git client.

  1. Download the installer from git-scm.com/downloads.
  2. Run the installer
    • Click Next
    • Click Next (to accept the license)
    • Click Next (to accept default components to install)
    • At the following prompt, select either of second or third options.
      git-setup.jpg
    • When prompted for the SSH executable, select "Use (Tortoise)Plink". If this option is not available, install TortoiseSVN and start over. There may be better options, but this one has been tested.
    • At the following prompt, select the third option.
      git-setup.jpg
    • Click Next to perform the installation.

Accessing Bitbucket

Next, you have to work back and forth between the BitBucket web site and the Windows Git client application, to set up their communication. Each student on your team should do this independently.

  1. Find the email inviting you to BitBucket; click on the link to accept the invitation. If you've already accepted, log in to bitbucket.org.

  2. In BitBucket, in the Repositories menu, select the repository called se2800-instructor (with the instructor name filled in appropriately). You should see the Overview page for the repository.

  3. In Windows, use Command-E to open a Windows Explorer window.
  4. Open the D: drive (double-click) and the right-click and select Git Bash from the context menu.
  5. Clone the repository to your local machine:

    • In the BitBucket/se2800-xxx window, make sure you are on the Overview tab.
    • On the right hand side, find a dropdown labeled SSH. (If it's showing HTTPS, switch it.)
    • Copy the text in the box to the right; this text will start with "git@bitbucket.org:"
    • In the Git Bash window, enter the command
      git clone
      (with a single space at the end), but do not press the Return key.

    • Move the mouse to the bar at the top of the window, right click, and select Edit->Paste. You should now have a command that resembles
      git clone git@bitbucket.org:sirjones/se2800-jones.git
      in the window.

    • Press Return.
    • If you get an error message about not being able to access the repository, make sure Pageant is running and has your key in it.
      • If Pageant is running, try rebooting your computer, re-running Pageant, and then re-doing the clone step.
    • If this is the first time you have accessed BitBucket on this machine, a window will pop up asking you about a fingerprint for BitBucket. Accept this key.
  6. View the files in your local directory by typing the ls command. Among other files listed will be se2800-xxx where xxx is your instructor's username; this is the top of your local repository.
  7. Enter the command
    cd se2800-xxx
    where "xxx" is your instructor's username to switch to the local repository directory.
  8. Type the ls command. You should see at least one file listed. You are now ready to add your own files to this repository.
  9. To add a file:
    • Enter the command
      start .
      (don't forget the ".") to open a Windows Explorer window displaying the current directory.
    • Right-click and select New->Text Document.
    • Name the text document "SE2800xyzLab2.txt" where "xyz" is your MSOE email username.
    • Open the file in your favorite editor, and add:
      • the names of your team members
      • the assignment identification ("SE-2800 Lab 2")
      • some other text lines of your choice.
    • Save the text file.
  10. In the Git Bash window:
    • Use the ls command to list directory contents.
    • Enter the command git add SE2800xyzLab2.txt
      This adds the file to the repository, but does not commit it.
    • Enter the command
      git commit
      to commit to your local repository. This will throw you into the Vim editor. Unless you're an old Unix hack, you probably don't want to be there. Press the escape key and then enter
      :q!
      followed by the Return key. You'll get a message about not being able to commit due to an empty message.
    • Let's try again by entering the command:
      git commit -m "My first git commit"
      Git will respond with a summary of the changes. Your changes are now committed to your local repository, but not to BitBucket. To confirm this, go to BitBucket, click on Source, and note that your file is not listed.
  11. The next step is to get your file up to BitBucket:
    • Enter the command
      git push
      and enter your BitBucket password when prompted. There's a chance this will work, but only if you're the first today to type the command. Most students will get an error about their version "being behind".
      To fix this by bringing down any changes from BitBucket, enter the command
      git pull
    • Next, enter the command
      git push
      Hopefully, this time it will work, but repeat pulls and pushes until your changes get copied up.
    • In the BitBucket window (your browser), use the Source tab to confirm your file is in the central repository.

Next, we are going to investigate what happens when conflicting changes are made:

  1. Each team member should edit one (the same one) of the team's files:
    • Make sure you have a copy of the current repository, using a
      git pull command.
    • Edit the chosen file by modifying an existing line of text.
    • Have your teammate edit the same file, modifying the same line of text in a different way. Note that each of you must modify the same line, because changes to different lines in the same file may be merged without causing a conflict.
    • Try to use the
      git pull command to retrieve changes from BitBucket. You will get an error about committing changes.
    • Add and commit your changes.
    • Use the git status command to tell whether you have diverged from the master and need to use git pull to merge in the remote files.
    • If necessary, use the
      git pull
      command.
    • By this time, Git should tell you there is a merge conflict. Enter the
      git status
      command again to get further information.
    • Although it is possible to directly edit the conflicted file (you may want to look at its contents), we will use TortoiseSVN's merge editor to fix the conflict. Invoke it with the command
      git mergetool
      and hit the Return key when prompted.
  2. Use the TortoiseSVN merge tool as follows:
    • Note there are three windows:
      • The bottom one contains the merged file - the one that will get checked in.
      • The upper left is the version that is already in the central repository; this is marked as "Theirs".
      • The upper right is the version that you checked in to your local repository; this is marked as "Mine".
    • Note the previous/next difference/conflict buttons on the toolbar. These can be used to jump from change to change. But for small files you probably won't need these.
    • You might find it useful to click on the Show Whitespaces button to get rid of the markings showing spaces and newlines.
    • To copy a block of code from the "Theirs" version to the resulting file, right click on the block and select "Use this text block". You can do the same thing from the upper right window as well.
    • You can also edit the merged version directly.
    • When you are done, click on the Mark as resolved button on the toolbar and save the file. Quit the merge tool.
  3. In the Git Bash window, enter the commands:
    git commit -m "Fixed conflict" -a
    git push
    (The "-a" option performs the "add" function prior to executing the commit.)
  4. Use the ls command to list files. There may be a version of the file with the extension .orig. If so, enter the command
    start .
    to bring up a Windows Explorer window and delete the file.
    (You can also use the rm command; type rm --help to get more information.)
  5. When you are done, enter the command
    exit
    to close the Git Bash window.