GIT Workflow for Teams

You can do a lot of things with GIT, and many of the rules of what you should do are not so much technical limitations but are about what works well when working together with other people. — Linus Torvalds, inventor of Linux and GIT

The following workflow is suggested for your team projects to minimize merge conflicts. It is based on using one branch per person in the team and using Gitlab's Merge Request to share each person's changes with the team (Merge Requests can also be an valuable tool to help team mates review and communicate about each other's code).

Clone the Project Repository

For team projects, each person should clone the team repository directly so that everyone is working on the same code base (there should be no reason to fork your own copy).

• In Terminal, each person in the team should clone the shared team repository:
  

      git clone git@coursework.cs.duke.edu:CompSci308_2024spring/PROJECT_teamNN.git

• In IntelliJ, create a New -> Open and select the folder you just created when you cloned the team repository to your local machine

One Branch per Person

The advantage of using one branch per person (instead per feature or package) is that it essentially assures that you are the only one using your branch, meaning you will only need to push your changes regularly so they are available in Gitlab and can be integrated into the main branch and you will not need to pull any new changes.

• Each person should create a branch for themselves to work on exclusively throughout the project:
  

      git checkout -b YOUR_NAME_OR_NETID

• Then you would work in this branch as usual during the project:

      git add YOUR_UPDATED_FILES
      git commit -m "A useful comment for your team mates about this change"
      git push -u origin BRANCH_NAME

In this way, each team member has a personal branch (a place to experiment or have Work In Progress, WIP) to work in and main becomes the team branch (a representation of the latest stable version of the entire project).

Integrate Your Changes with the Team

Merge Requests are a powerful tool provided by many online GIT repositories (including GitHub and BitBucket). It creates a web page representing the changes you intend to make to the repository in an easy to understand format that allows others to comment on your changes before accepting them. The request's web page also updates automatically to reflect new changes that are committed and pushed until it is closed.

• Rather than working directly with the default branch on your local machine, use Gitlab's Merge Request tool to manage integration
• When you are ready to integrate your changes with the team's latest stable version of the project in the main branch, go to the team's project repository web page
  
• Select Merge Requests → New Merge Request from the project website's left sidebar and then on the resulting page
• Select your branch as the Source Branch and main as Target Branch (main is the default), then select Compare branches and continue
• If there are no conflicts, then simply wait for another person on your team to approve the Merge Request
• If there are conflicts, then your team will need to resolve them, either directly on the web page or by changing the code locally and pushing it again (the Merge Request will automatically incorporate the changes)
  Note, if you do resolve the conflicts using the online interface you will need to pull those changes down to your branch's local copy before doing the next steps.

In summary, push your personal branch changes to Gitlab and create a Merge Request to the main, team, branch.

Integrate the Team's Changes with Your Code

This step is most likely to contain merge conflicts since you have been coding on your branch without worrying about what the rest of the team has been doing (so the longer you wait to push your code the more likely it is that you will cause conflicts).

• After a Merge Request has been accepted by the team, there will be new code on the main branch
• To merge this new code with your personal branch, you can do one of these options:
  1. Use a Merge Request on Gitlab (as above) from the main branch to your personal branch
     This has all the advantages noted above, including being able to use the web interface to resolve conflicts, and will require you to pull the changes down to your local repository after finishing.

     git checkout -b YOUR_NAME_OR_NETID
     git pull

     Also, using the web interface means you will never need to "leave" your branch on your local machine.
  2. Use the command line to merge directly. This can be more stream lined, especially if there are no conflicts
  • You need to change into the main branch on your local machine to pull down the new changes
    

        git checkout main
        git pull origin main

  • This merge should proceed smoothly since you have not made any local changes to the main branch
  • Change back into your personal branch to merge the new changes now in the main branch
    

        git checkout BRANCH_NAME
        git merge main

  • This is where you may get conflicts. If so, fix them (perhaps by consulting with your team mates) and create a commit just for the fixes and push it up to Gitlab as usual.

        git add YOUR_UPDATED_FILES
        git commit -m "A useful comment for your team mates about this change"
        git push -u origin BRANCH_NAME

• Take a moment to admire the new updates to your project, then get back to work on your part of the project :)

In summary, merge the main, team, branch changes with your personal branch (either remotely via Merge Request or locally via the Terminal) and pull them to your computer.