Getting Started with Our Repository in VSCode

[doctorbanu]

A Beginner's Guide to Working with Git Repos in VSCode

🖇️ Cloning the Repository 🖇️

a) We can open VSCode, and on the main page, click on
"Clone Git Repository".
b) Alternatively, we can open the terminal and run the following command
for our Repo:
git clone https://github.com/MIT-Emerging-Talent/ET6-foundations-group-05.git

---

🌿 Branch Creation and Commands for Branch Management 🌿

• To avoid risking the main branch, we will work on separate branches.

🗒️Note: Branch Naming Tips
We need to use meaningful names related to our task.
Example: Collaboration_Learning_Goals

a) Check status of our working directory and staging area

git status

• This command shows:
  • Which branch we're on
  • Changes not staged for commit
  • Changes staged for commit
  • Untracked files

b) Check existing branches (local)

git branch

c) Check all branches (local and remote)

git branch --all

d) Update our local repository to the latest version of main

git pull origin main

e) Merge another branch into your current branch

git merge another_branch_name

Example: While on our working branch, to merge main into it: git merge main

f) To switch between branches

git switch name_of_wanted_branch

g) Create a new branch and switch to it

• We can do it in one command with this command: git checkout -b name_of_new_branch
• Or, in separate steps:
  • Create a new branch: git branch name_of_new_branch
  • Switch to the new branch: git switch name_of_new_branch

🗒️Note: Both creation options are valid.

h) Delete branches

• Delete a local branch: git branch -d branch_name
• Force delete a local branch (if changes are not merged): git branch -D branch_name
• Delete a remote branch: git push origin --delete branch_name

❗🗒️IMPORTANT NOTE: Updating our local repo regularly is very important
in order to avoid large conflicts.

• We can follow these steps with this order to keep our local branch up to date:

git switch main

git pull origin main

git switch our_branch

git merge main

• If we get conflicts, we can resolve them following the steps in
  "Handling Merge Conflicts" section down below.

---

🚀 Making and Pushing Changes to GitHub 🚀

1. Staging Changes

• ❗Avoid using git add .

  • Because, using it stages all changes in the repository, which can unintentionally
    include unrelated files or changes and cause conflicts.

• Preferred Alternative: Add specific files only with: git add folder_name/file_name

Example: git add solutions/solution.py

2. Committing Changes

• After staging, commit your changes with a descriptive message:
  git commit -m "Descriptive message, e.g., Added solution and tests for challenge_name"

🗒️Note: The quotes are required for the message.

3. Pushing to GitHub

• Push your branch to GitHub: git push origin branch_name

❗🗒️Important Note: In our particular repository, direct pushes to the
main branch are blocked. So, git push origin main will not work.
To merge changes into the main branch, we will create a Pull Request (PR)
after pushing our branch.

---

🔄 Pull Requests and Reviews 🔄

1. Creating a Pull Request (PR)

🗒️Note: Before creating a Pull Request,
we need to ensure all work is
completed on our branch, and commit and push all changes to GitHub.

a) If our branch is recently pushed, GitHub will display a Compare & Pull Request
button.

• We can click it to start creating a PR.

b) Alternatively, we will:

• Go to the Pull Requests tab on the GitHub repository.
• Click New Pull Request.
• Select the branch and the branch to merge into (e.g., main).
• Click Create Pull Request.

2. Reviewing a Pull Request

If we are reviewing someone else's pull request. We will:

• Go to the Pull Requests tab in the repository.
• Click the pull request to review.
• Review the changes and leave comments if necessary.
• Approve or request changes.

🗒️Note: Tips for Reviewing
We need to check if the branch meets all quality standards.
We will ensure the code is clear, functional, and tested.

---

🔗 Merging 🔗

Once the PR is approved, we need to click the green "Merge pull request" button
and then "Confirm merge". After successful merge, our changes will be added to
the main branch.
🎉 And, congratulations! Once the PR is merged, our solution is part of the repository.

🗒️Note: If we see a "Merge conflicts" message instead of the merge button,
we'll need to resolve conflicts first. 😓 We can follow the steps in
"Handling Merge Conflicts" section below, or contact our team lead or
experienced team member for assistance.

Handling Merge Conflicts

If we get conflicts while merging main into our branch:

1. Get Latest Changes from Main: git switch main and then, git pull origin main
2. Switch Back to Our Branch: git switch our_branch
3. Merge Main into Our Branch: git merge main

• At this point, we might encounter conflicts.(GOD FORBID🥲) And Git will indicate
  which files have conflicts that need to be resolved.
• To resolve conflicts: We open the conflicted files in VSCode and look for
  conflict markers (like <<<<<<<, =======, and >>>>>>>). We need to edit the files
  manually to resolve the conflicts and keep the desired changes.
• To mark resolved files: Once we've resolved the conflicts in each file, we
  need to add those files to the staging area: git add resolved_file
• Finally, to commit the merge with a message:
  git commit -m "Merge main and resolve conflicts"

[doctorbanu]

Hi guys! 🙋🏻‍♀️ I added a guide for Git commands that can be useful for us. And I tried to include the important things to keep in mind. I know it seems a little bit too long, but I am going to add a summary for it. However, it could be better if you can check the original version.

[doctorbanu]

Summary

1. Clone the Repository

a) Open VSCode, and click on "Clone Git Repository".
b) Or, open the terminal and run:
git clone https://github.com/MIT-Emerging-Talent/ET6-foundations-group-05.git

2. Branch Creation

a)git checkout -b name_of_new_branch
With this command we will create a new branch and move in it.
b) Or,
git branch name_of_new_branch (This creates a new branch.)
AND
git switch name_of_new_branch (This switches to the new branch we will work on.)

! Important:
The name of the new branch must be releated to the task we will work on.

3. Staging and Pushing Our Changes to GitHub

• First, git add file_name (Avoid git add .)
• Then, git commit -m "Descriptive message, e.g., Added solution and tests for challenge1" (the quotes are required for the message. )
• Finally, git push origin branch_name

! Important:
For our project, direct pushes to the main branch are blocked. So, git push origin main does not work.
To merge changes into the main branch, we need to create a Pull Request (PR) after we push our branch.

4. Pull Requests and Reviews

Creating a Pull Request (PR)
a) Go to the GitHub webpage and click the Compare & Pull Request button on the repository page.
b) Or, go to the GitHub webpage and:

• Click the Pull Requests tab -> New Pull Request.
• Select our branch and the branch we want to merge into (e.g., main) -> Click Create Pull Request.

! A teammate will review our Pull Request. During the review, they might approve it or request changes. The branch owner or reviewer can merge the Pull Request once it's approved.

Congratulations! 🎉

[misik-eng]

We added this to Notes Folder. Thank you Banu!