Welcome to Git and GitHub at ChaiCode Cohort! ☕️
Introduction
Welcome to ChaiCode! Git and GitHub are the backbone of our development workflow. Git helps track code changes like a time machine for your projects, while GitHub provides a platform for seamless collaboration. This guide will get you up and running with both tools in no time. Let’s brew some code!
Basics of Git and GitHub
What is Git?
Git is a version control system that tracks changes to your code, helping you manage and review revisions over time.
What is GitHub?
GitHub is a platform where teams host, review, and collaborate on code. It’s where we share our "chai recipes" (projects) and work together to build great software.
Installation and Setup
Step 1: Install Git
Windows
Download Git from git-scm.com.
Run the installer and follow the prompts (keeping the default settings):
Choose a text editor (e.g., Vim, Notepad++, or Visual Studio Code).
Ensure Git is added to your system PATH (recommended for command-line usage).
Select the default option (OpenSSL) for secure Git communication.
Use "Checkout Windows-style, commit Unix-style line endings" for compatibility.
Verify the installation by opening Command Prompt and typing:
git --version
macOS Installation
Option 1: Install Git via the Mac App Store
Open the Mac App Store:
Launch the App Store from your Dock or via Spotlight Search.
Alternatively, visit the Mac App Store website.
Search for Git:
Type "Git" in the search bar.
Select a Git client like GitUp or another GUI tool that supports Git.
Install and Verify:
Click Get or Install to download the app.
After installation, open Terminal and verify Git with:
git --version
Git Installation on Ubuntu
Step 1: Update System Packages
Before installing Git, update your system:
sudo apt update
sudo apt upgrade -y
Step 2: Install Git
Install Git using the git-all package:
sudo apt install git-all
Step 3: Verify Installation
Check if Git is installed correctly:
git --version
Example output:
git version 2.34.1
Step 4: Configure Git
Set your username and email (use your ChaiCode credentials):
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
Verify your configuration:
git config --global --list
Step 5: Create a GitHub Account
Go to github.com.
Click Sign Up and follow the steps.
Enable Two-Factor Authentication (2FA) for enhanced security (required at ChaiCode).
Cloning the ChaiCode Repository
When you create a repository on GitHub, it exists as a remote repository. Cloning creates a full copy of this repository on your local machine, allowing you to work offline, resolve merge conflicts, add or remove files, and push updates back to GitHub.
Step 1: Navigate to the Repository on GitHub
Open your web browser and go to the ChaiCode repository page:
https://github.com/ChaiCode/example-repo.git
(Replace the URL with the actual repository URL if needed.)On the repository’s main page, locate the Code button above the list of files.
Click the Code button to reveal the cloning options.
Step 2: Copy the Repository URL
In the Code dropdown, ensure you have selected the HTTPS tab (or SSH if you prefer that method).
Click the copy icon next to the URL to copy the repository link to your clipboard
.
Step 3: Open Your Terminal
Open your command-line interface. Depending on your operating system, you might use:
Windows: Git Bash or Command Prompt
macOS/Linux: Terminal
Change the current working directory to the location where you want to save the cloned repository.
Step 4: Clone the Repository
In your terminal, type the following command and paste the URL you copied:
git clone https://github.com/ChaiCode/example-repo.git
Press Enter to run the command. This will download the full repository data (including commit history and branches) to your local machine.
Step 5: Navigate into the Cloned Repository Folder
Once cloning is complete, navigate into your newly created repository folder using the cd command:
cd example-repo
This command changes your current directory to the cloned repository, allowing you to start working on your project locally.
Basic Git Commands
Below is a section covering basic Git commands along with examples and placeholders for screenshots. You can reuse this section as needed.
1. git status
Displays the state of your working directory and staging area.
git status
2. git add
Stages changes to be committed. You can add a single file or all changes.
Add a single file:
git add filename.txt
Add all changes:
git add .
Example of staging changes using git add.
3. git commit -m "message"
Commits the staged changes with a descriptive message.
git commit -m "Add new feature"
4. git push
Pushes your local commits to the remote repository. Replace main with your branch name if different.
git push origin main
5. git pull
Fetches and merges changes from the remote repository into your local branch.
git pull origin main
6. git log
Displays a log of the repository’s commit history.
git log
Branching Workflow
At ChaiCode, we use a structured branching strategy to keep our codebase stable and facilitate efficient development. Our workflow is organized as follows:
main: Contains production-ready code.
development: Acts as the integration branch where new features and fixes are combined and tested.
feature branches: Each new feature or bug fix is developed in its own branch (e.g.,
feature/tea-menu), keeping work isolated until it's ready to merge.
Creating and Switching Branches
To create a new feature branch and switch to it, use the following commands:
git branch feature/tea-menu
git checkout feature/tea-menu
Alternatively, combine both steps into one command:
git checkout -b feature/tea-menu
This creates the branch feature/tea-menu and immediately switches your working directory to it.
Merging Branches
Once you've completed work on a feature branch, follow these steps to merge it into the development branch:
Switch to the development branch:
git checkout developmentMerge the feature branch into development:
git merge feature/tea-menu
If Git detects conflicts during the merge, you'll need to resolve them manually.
Resolving Conflicts
When merge conflicts occur:
Identify the Conflicts:
Git marks the conflicting sections in affected files with markers (e.g.,<<<<<<<,=======, and>>>>>>>).Resolve the Conflicts:
Open each conflicted file and edit it to reconcile the differences between branches.Mark the Files as Resolved:
After resolving conflicts, add the updated files:git add <filename>Finalize the Merge:
Complete the merge by committing the changes:git commit -m "Merge feature/tea-menu into development, resolving conflicts"
Pull Requests (PR)
Pull requests allow you to propose and collaborate on changes to a repository. They are created from a feature or topic branch, ensuring that the base branch contains only finished and approved work.
Creating a Pull Request
Prepare Your Branch:
Ensure your changes are committed to a branch different from the base branch (usuallymainordevelopment).Navigate to the Repository on GitHub:
Open your repository in a web browser.
Click the Pull Requests tab.
Click New Pull Request.
Select the Branches:
In the "base:" dropdown, select the branch where you want your changes merged.
In the "compare:" dropdown, select your feature branch.
Ensure that the two branches are different.
Preview the Changes:
GitHub displays a diff of the changes between the selected branches. Review the changes carefully.
Create the Pull Request:
Click Create Pull Request.
Enter a clear title and detailed description for your pull request.
For reference, check out the Azure DevOps Pull Requests Documentation.
Guidelines for a Good PR Description
Title: Use a concise title that summarizes the changes.
Description:
Explain the context and purpose of your changes.
Describe the problem being solved and how your changes address it.
Mention any related issues using
#issue_numberto link them.Include screenshots or additional details if your changes affect the user interface.
Requesting Code Reviews:
Tag relevant team members or collaborators in the reviewers’ section.
Provide any extra context or instructions needed for an effective review.
Submitting Your PR
Ready for Review:
If your work is complete and ready for feedback, click Create Pull Request to submit your changes.Draft PR:
If your work is still in progress, select Create Draft Pull Request to indicate that it’s not yet ready for final review.
Best Practices
To maintain a healthy and collaborative codebase, follow these Git best practices:
1. Commit Regularly
Why Commit Regularly?
Regular commits help track progress incrementally, making it easier to debug, revert changes if needed, and understand the project history.When to Commit?
After completing a small, logical piece of work.
When fixing a bug or adding a new feature.
Periodically, to save your work and ensure nothing is lost.
2. Use Descriptive Commit Messages
Importance:
Clear commit messages help your team—and your future self—understand the context and purpose of changes without reviewing the entire diff.Guidelines:
Summary: Start with a concise summary (ideally 50 characters or less).
Details: Optionally add a longer explanation that describes what was changed and why.
Style: Use the imperative mood (e.g., "Add", "Fix", "Update").
Example:
git commit -m "Add user login feature with validation"
3. Pull Updates Regularly
Staying Up-to-Date:
Frequently pulling updates from the remote repository ensures your local branch includes the latest changes, reducing the likelihood of merge conflicts.When to Pull:
Before starting new work.
Right before committing changes.
When switching between branches.
Example command:
git pull origin main
By incorporating these practices, you'll help ensure a smooth, efficient, and collaborative development process for everyone on the team.