README.md - git-github-guide

A guide that explains how to use Git and GitHub for version control and collaboration, while demonstrating the workflow and structure of a real-world collaborative project. Readers will learn how to set up Git, create and manage branches, open and review pull requests, resolve merge conflicts, track project changes, and organize work using GitHub Issues and Project Boards.

Demonstration

Video on YouTube (05:01) for demonstration and explanation purposes of Git & GitHub Guide.

• https://youtu.be/-dMMeqPvmUc

Table of Contents

1. Understanding Version Control Systems
2. Getting Started with Git
3. Tracking and Managing Changes
4. Create and Switching Branches
5. Merging and Conflict Resolution
6. Working With GitHub
7. Review and Future Learning

Understanding Version Control Systems

A Version Control System (VCS) records changes to files over time, allowing developers to track revisions, revert mistakes, and safely merge updates. VCS is an essential tool for both individual developers and collaborative teams.

Advantages of Version Control:

1. Track Changes and Revert Easily Whenever you make a set of related changes and commit them, the VCS records what changed, who made the changes, when they were made, and why through a descriptive commit message. This enables you to undo mistakes and revert to earlier versions, understand the history and evolution of the project, and experiment safely using branches. If an experiment fails, you can delete the branch; if it succeeds, you can merge it.

2. Collaborate Smoothly (Avoid Overwrites) Teams can work on the same project at the same time without overwriting each other’s work. A VCS supports merging, highlights conflicts, maintains accountability, and integrates with central repositories such as GitHub to ensure everyone is working with the most up-to-date version of the code.

Without version control, mistakes are permanent, collaboration is chaotic, and project history is difficult to track. Using Git records every change, makes experimentation safe, streamlines teamwork, and provides a clear, traceable project history, making it an essential best practice for any software project.

Getting Started with Git

To use version control and collaborate with others, install Git locally on your computer and create a GitHub account. Git manages your project’s history locally, while GitHub provides a central place to store your code, work efficiently with others, and track project changes.

1. Install Git

• Go to the official Git website: https://git-scm.com/downloads.
• Select your operating system (Windows, macOS, Linux/Unix) and follow the instructions.

2. Configuring Git

Configure Git with the name and email address to be associated with every change (commit) you create.

1. Open terminal (Git Bash on Windows, Terminal on macOS/Linux).
2. Set your username (Use your actual name, ideally the same one you'll use for GitHub):

git config --global user.name "Your Name"

3. Set your email address (Use the email associated with your GitHub account):

git config --global user.email "your.email@example.com"

4. You can verify your settings by using the command:

git config --global --list

3. Setting Up a GitHub Account

GitHub is the most popular platform for hosting Git repositories.

1. Go to GitHub's website: https://github.com/
2. Sign up for a new account: Follow required prompts to enter email, password, username, and country/region.
3. Verify your email address: GitHub will send a verification email that contains a link to activate your account.

4. Setting up SSH keys for GitHub Authentication

Instead of typing your GitHub username and password every time (e.g., when you push or pull code), you can set up SSH keys. SSH keys let your computer securely and conveniently connect to GitHub.

1. Check for existing SSH keys. Open your terminal and run:

ls -al ~/.ssh

Look for files named id_rsa.pub or id_ed25519.pub. If you find one, you may not need to create a new key.

2. Generate a new SSH key (if needed): Run the following command, replacing the email with your GitHub email:

ssh-keygen -t ed25519 -C "your.email@example.com"

- Press Enter to accept the default file location (~/.ssh/id_ed25519).
- When prompted for a passphrase, you can enter one for extra security or leave it blank.

3. Start the SSH (if not running), run:

eval "$(ssh-agent -s)"

• On Windows with Git Bash, the SSH agent usually starts automatically.

4. Add your SSH key to the SSH agent:

ssh-add ~/.ssh/id_ed25519

• If you used id_rsa instead, replace id_ed25519

5. Copy your public SSH key:

• macOS/Linux:

pbcopy < ~/.ssh/id_ed25519..pubc

• Windows (Git Bash):

cat ~/.ssh/id_ed25519.pub

Then manually copy the output.

6. Add the SSH key to your GitHub account:

1. Go to GitHub's website (https://github.com/).
2. Log in.
3. Click your profile picture -> Settings -> SSH and GPG keys -> New SSH key.
4. Give it a descriptive title (e.g., "My MacOS Device").
5. Paste your copied public key into the Key field and click Add SSH key.

7. Test your SSH connection:

• Open the terminal, run:

ssh -T git@github.com

You should see a message similar to: Hi username! You've successfully authentiated..."

The first time, it may ask you to confirm the authenticity of the host.

Once Git is installed and configured, and your GitHub account has an SSH key, you're ready to start creating and managing repositories.

5. Creating a Remote Repository on GitHub

A remote repository is a copy of your project stored on GitHub, serving as a central hub for backup and collaboration.

1. Log in to GitHub's website.
2. Click New (green button on the sidebar or + icon -> New repository).
3. Enter a repository name (short, memorable, use hyphens instead of spaces).
   • Optional: Add a description.
4. Choose Public (open access to anyone) or Private (restricted access).
   • Recommended: Check Initialize with README to create a default branch.
   • Optional: Add a .gitignore template or license if needed.
5. Click Create repository.

Your remote repository is now ready for collaboration and code backup.

6. Cloning a Remote Repository to Local Machine

Cloning creates a local copy of a GitHub repository on your local device so you can start working on it.

1. Copy the repository's SSH URL from GitHub (Code -> SSH).
2. Open a terminal and navigate to the desired folder where you want to store the project.
3. Run:

git clone git@github.com:your-username/your-repo-name.git
cd your-repo-name

You can now start working locally and push changes back to GitHub.

Basic Git Workflow

1. Edit files locally.
2. Stage changes:

git add . # or git add <file_name>

3. Commit changes:

git commit -m "<descriptive, clear message explaining what you changed and why>"

4. Push to GitHub:

git push origin main # or name of branch

5. Update local repository:

git pull origin main # or name of branch

This workflow keeps your local and remote repositories in sync and ready for collaboration.

Tracking and Managing Changes

Committing changes in Git creates a 'snapshot' of your project at a specific point in time. This records your work in Git's history, enabling you and your team to track changes, revert to earlier versions, and collaborate efficiently.

Staging Area and Workflow

Git uses a staging area (index), a powerful feature that allows you to selectively choose which changes you want to include in your next commit.

• Working Directory: Where you edit files.
• Staging Area (Index): Where files are staged to include in the next commit.
• Repository (History): Where commits are permanently stored in Git's history.

Commands

• Check current state of your working directory and staging area, shows modified, staged, or untracked files:

git status

• Stage changes:

git add <file>  # specific file
git add .  #all changes
git add -u  #only updates to tracked files

• Unstage changes:

git reset <file>

• Committing staged changes:

git commit -m "Your descriptive message"

• Without -m, Git opens a text editor for a longer message.

  Best commit message practices:

  • Subject line (first line): concise, imperative, 50-72 characters Examples:
    • Implement: Add get_history function to validate and retrieve logging history
    • Refactor: correct spacing and line breaks to adhere to PEP 8 guidelines
  • Body (optional): detailed explanation, why the change was made, wrapped at 72 characters. Avoid obvious code details; focus on intent.

• Viewing commit history:

  • Basic log: git log
  • Quick overview: git log --oneline or git log --graph --oneline --decorate
  • Show diffs: git log -p
  • Filter by author, keyword, file, or date:

git log --author="Your Name"
git log --grep="keyword"
git log <file>
git log --since="2 weeks ago"

To exit any git log view, press q.

Summary Workflow

1. Modify files in your working directory.
2. Stage changes: git add <file>
3. Commit changes: git commit -m "Descriptive message explaining what/why"
4. Log history to review: git log

Mastering the staging area, crafting descriptive commit messages, and navigating the commit history gives you clear control over the project and improves effective collaboration.

Creating and Switching Branches

Branching allows you to work on new features, bug fixes, or experiments in isolation without affecting the main codebase.

Understanding Branches

• Branch: A separate line of development. Changes on a branch do not affect others until merged.
• Main (or master): The default branch, usually stable and deployable.
• Feature Branch: For developing new features.
• Bugfix Branch: For fixing issues without affecting other work.
• Experiment Branch: For testing ideas that may not be merged.

Why Use Branches?

• Safety: Work independently without breaking the main branch.
• Parallel Work: Multiple developers can work simultaneously on different branches.
• Experimentation: Try new ideas safely; discard if necessary.
• Organization: Manage different versions or stages of your project.

Common Branch Commands

• List all local branches (The active branch is marked with *.): git branch
• Create a new branch: git branch <branch-name>
  • Creates a branch but does not switch to it.
  • Tip: Use descriptive names like feature/login or bugfix/header-fix.
• Switch branches:

git checkout <branch-name>  # Traditional
git switch <branch-name>  # Recommended in Git 2.23+

If you have uncommitted changes, commit, stash (git stash), or discard them (git restore .) before switching.

• Create and switch in one step:

git checkout -b <branch-name>  # Traditional
git switch -c <branch-name>    # Recommended

Example Workflow: Adding a Feature

1. Ensure you are on main branch: git branch # shows * main
2. Create and switch to a new branch: git switch -c feature/login
3. Make changes and stage them: git add login.py
4. Commit your changes: git commit -m "Implement: add user login functionality"
5. Switch back to main if needed: git switch main Changes on your feature branch remain isolated until merged.
6. Continue working on the feature branch: git switch feature/login

Visualizing Branch History

Displays branch structure, showing commits and merges: git log --graph --oneline --decorate

Deleting Branches

git branch -d <branch-name>   # Deletes a fully merged branch safely
git branch -D <branch-name>   # Force delete an unmerged branch

GitHub also allows you to delete and restore branches directly from the Pull Requests.

Branching keeps development organized, supports teamwork, allows experimentation, and ensures your main branch remains stable.

Merging and Conflict Resolution

To integrate a feature or bugfix branch into main branch, use the git merge command:

1. Switch to the branch you want to merge into: git switch main # or git checkout main
2. Update it with the latest changes from the remote repository: git pull origin main
3. Merge the source branch: git merge <source-branch-name> Example: git merge feature/user-login

Merge Types

• Fast-forward: main hasn't changed; moves forward.
• 3-way merge: both branches have new commits; Git creates a merge commit to combine histories.

Merge Conflicts

Conflict occurs when the same lines are changed in both branches. An example of how Git marks conflicts:

<<<.... HEAD
# main branch code
=======
# feature branch code
>>>.... feature-branch

Resolve Conflicts

1. Edit file to keep desired code and remove markers.
2. Stage and commit:

git add <file_name>
git commit

Tips on Handling Merge Conflicts

• Communicate with teammates to resolve conflicts: Conflicts usually involve a part of code. Communicating ensures you to keep the correct changes.
• Merge frequently to reduce conflicts: Regularly merging small changes keeps your branch up-to-date and makes conflicts easier to resolve.
• Use IDE (Integrated Development Environment) tools for easier conflict resolution: Editors like Visual Studio Code highlight conflicts visually and let you choose changes safely, making conflict resolution more efficient and simple.

Working with GitHub

This section covers working with GitHub pull requests, forking and cloning repositories, managing .gitignore files, best practices for maintaining project hygiene, and using GitHub tools such as Issues and Project Boards.

Pull Requests

A pull request (PR) allows you to propose changes from a feature branch to the main branch on GitHub. It provides a platform for review, discussion, and collaboration before the changes are merged.

Pull Request Workflow

1. Create a Branch: git checkout -b feature/new-login-page

• Work on a feature or fix independently, keeping the main branch stable.

2. Make Changes and Push:

git add .
git commit -m "Description of what/why for changes"
git push origin feature/new-login-page

3. Open a Pull Request:

• On GitHub, click New pull request.
• Select your feature branch as the compare branch and main as the base branch.
• Add a clear title and description of your changes.

4. Code Review:

• Reviewers can view changers (diffs), leave comments, and approve or request updates.
• A PR cannot be merged until all requested changes are addressed.

5. Merge the Pull Request:

• Click the green Merge pull request button once approved.
• Resolve any conflicts locally or directly in GitHub before merging.
• By default, GitHub creates a merge commit. You can also choose squash and merge or rebase and merge.

Best Practices for PRs

• Keep PRs small and focused.
• Write clear descriptions explaining what changed, why, and any context.
• Review promptly to prevent outdated branches.
• Self-review your code before submitting.
• Update your branch with main regularly to avoid conflicts.

Forking and Cloning Repositories

To contribute to a project or work from a shared repository, you need to fork and clone it. Forking creates your own copy on GitHub, while cloning downloads it to your local machine.

Forking a Repository

• Purpose: Creates a personal copy of a project, allowing you to experiment and make changes without affecting the original.
• How: Click the Fork button on the project's GitHub page. Your fork is linked to the original ("upstream") repository.

Cloning a Repository

• Purpose: Downloads a repository to your local machine so you can edit files, create branches, and commit changes.
• How:
  1. Go to the repository on GitHub (original or your fork).
  2. Click Code -> copy the URL (SSH recommended).
  3. Open terminal, navigate to the desired folder.
  4. Run: git clone <repository-url>

Example Workflow for Contributing

1. Fork the repository on GitHub.
2. Clone your fork locally: git clone git@github.com:your-username/project-name.git
3. Develop on a new branch:

git checkout -b feature/design-colorways
git commit -m "Add new feature to design colorways"

4. Push your branch to your fork: git push origin feature/design-colorways
5. Open a Pull Request on GitHub to propose changes to the original repository.

Keeping your Fork Up-to-Date

1. Add the original repository as an upstream remote: git remote add upstream <original-repository-url>
2. Fetch and merge updates:

git fetch upstream
git merge upstream/main

This ensures your fork stays current and avoids merge conflicts.

Git Ignore and Project Hygiene

.gitignore

A .gitignore file tells Git which files or folders to skip, keeping your repository clean. It prevents tracking temporary files, build artifacts, IDE settings, or sensitive data.

Benefits:

• Clean repositories: Avoid clutter from unnecessary files.
• Security: Prevent accidental commits of passwords, keys, or credentials.
• Consistency: Stop local environment files from affecting others.
• Smaller repositories: Reduce repository size.

Usage:

1. Create at the project root: touch .gitignore
2. Add patterns to ignore:

*.log         # All .log files
env/          # Environment folder
build/output/ # Specific folder
!README.md    # Track README.md even if others are ignored

3. Stop tracking a file already committed:

git rm --cached unwanted_file.log
git commit -m "Stop tracking unwanted_file.log"

Best Practices for .gitignore

• Add .gitignore file at the start of a project.
• Use templates for your language/framework.
• Only ignore irrelevant files.
• Never commit secrets; use environment variables instead.

Issues and Project Boards

GitHub provides built-in tools to organize tasks and track progress: Issues and Project Boards.

Issues

Track tasks, bugs, or feature requests.

• Create: Clear title and detailed description.
• Assign: Designate a team member responsible for the task.
• Labels: Categorize tasks (e.g., bug, enhancement, documentation).
• Milestones: Group related tasks by goal, release, or timeline.

Project Boards

Visualize progress using a Kanban-style workflow.

• Columns: Represent workflow stages like To Do, In Progress, Done.
• Cards: Each issue or pull request appears as a card; drag between columns to update its status.
• Automation: Move cards automatically (e.g., when a linked pull request is merged, the issue moves to Done).

Example of Workflow using Issues and Project Boards:

1. Create an issue, assign it, and label it.
2. Move the card to "In Progress" and create a branch to fix it.
3. Submit a pull request linked to the issue (e.g., Fixes #42).
4. Merge the PR; the issue closes, and the card moves to Done.

This workflow keeps work organized, progress visible, and collaboration smooth.

Review and Future Learning

This guide introduced the core concepts and essential workflows for version control and collaboration using Git and GitHub. It covered how to manage repositories, create and merge branches, resolve conflicts, and use pull requests to support effective code review and teamwork.

Next Steps

• Contribute to open source: Begin engaging with beginner-friendly repositories on GitHub. Practice the complete workflow of forking, cloning, modifying code, and submitting pull requests to gain real-world collaboration experience.
• Explore advanced workflows: Deepen your understanding of version control by studying Git Flow, branching models, continuous integration, and automated testing pipelines commonly used in professional development environments.
• Collaborate in teams: Participate in group projects to develop teamwork and communication skills. Practice code review, apply agile methodologies, and use project management tools to coordinate tasks and maintain high-quality, organized codebases.