GitHub Repository Management: Tips and Tricks for Beginners

Quick Reference Guide

Setting Up

# New repository
git init

# Connect to GitHub
git remote add origin https://github.com/username/repo.git

# Get existing repository
git clone https://github.com/username/repo.git

Daily Work

# Get latest changes
git pull

# Create new branch
git checkout -b new-feature

# See what you've changed
git status

# Add changes
git add filename.js

# Commit changes
git commit -m "Add new feature"

# Send to GitHub
git push origin new-feature

Fixing Mistakes

# Undo uncommitted changes
git checkout -- filename.js

# Undo staged changes
git reset HEAD filename.js

# Undo last commit
git reset --soft HEAD~1

Introduction

GitHub helps teams work together on code projects by keeping track of changes and allowing multiple people to collaborate. This guide covers essential tips and explanations to help you manage GitHub repositories effectively, even if you're just getting started.

Git and GitHub: The Basics

Before diving into tips and tricks, let's understand some key terms:

Key Terminology Explained

• Repository (or "repo"): Think of this as a project folder that Git keeps track of. It contains all your project files and the history of changes made to them.

• Commit: A snapshot of your files at a specific point in time. When you "make a commit," you're essentially saying "save these changes to my project's history."

• Staging Area: A temporary holding area where you put files before committing them. Files must be "staged" before they can be committed. Think of it as a preparation area where you decide what changes should be saved in your next commit.

• Remote: A version of your repository that lives on a server (like GitHub) instead of on your computer. When you "push to remote," you're sending your local changes to the shared version online.

• Clone: Making a copy of a remote repository on your local computer so you can work on it.

• Branch: A separate version of your code that allows you to work on features or fixes without affecting the main project until you're ready.

• Merge: Combining changes from different branches together.

• Pull Request: A request to merge changes from one branch into another, typically used to review code before it becomes part of the main project.

Repository Setup and Organisation

1. Starting a New Repository

You can create a new repository in two ways:

On GitHub directly:

1. Log in to GitHub
2. Click the "+" icon in the top right and select "New repository"
3. Name your repository and add a description
4. Choose public or private
5. Click "Create repository"

From an existing project on your computer:

# Navigate to your project folder
cd my-project

# Initialize it as a Git repository
git init

# Connect it to a GitHub repository you've created
git remote add origin https://github.com/yourusername/your-repository.git

2. Essential Repository Files

These files make your repository more useful and user-friendly:

• README.md: This file appears on your repository's homepage. It should explain what your project does, how to set it up, and how to use it.

• LICENSE: Tells others what they're allowed to do with your code (e.g., can they use it in commercial projects?).

• CONTRIBUTING.md: Guidelines for how others can contribute to your project.

• CHANGELOG.md: A record of all notable changes made to the project.

Understanding .gitignore

The .gitignore file tells Git which files to ignore and not track. This is useful for:

• Files containing sensitive information (passwords, API keys)
• Files generated during the build process
• Large files that don't need version control
• System files specific to your computer

Creating a .gitignore File

1. Create a file named exactly .gitignore in your repository's root directory
2. Add patterns for files or folders you want to ignore

# Example .gitignore file with explanations

# Ignore operating system files
.DS_Store    # Mac OS system files
Thumbs.db    # Windows image file cache

# Ignore editor-specific files
.vscode/     # Visual Studio Code settings
.idea/       # IntelliJ IDEA settings

# Ignore dependency directories (where external libraries are stored)
/node_modules/    # Node.js packages
/vendor/          # PHP or Ruby packages

# Ignore compiled output
/build/
/dist/

# Ignore environment files that might contain secrets
.env
config.local.js

# Ignore log files
*.log

Tips for Using .gitignore

1. Use templates: When creating a repository on GitHub, you can select a template .gitignore for your programming language.

2. Test your settings: To check which files are being ignored, use:

   git status --ignored

3. Pattern guide:

   • file.txt - Ignores this specific file
   • *.txt - Ignores all files with .txt extension
   • logs/ - Ignores the entire logs directory
   • !important.txt - Does NOT ignore this file (even if it matches an earlier pattern)

What is .gitkeep?

Git doesn't track empty folders. If you want to include an empty folder in your repository (for example, a folder that will hold files generated later), you can add a .gitkeep file to it.

How to Use .gitkeep

Simply create an empty file named .gitkeep in any folder you want to keep in your repository, even when it's empty:

# Create an empty folder and add .gitkeep to it
mkdir images
touch images/.gitkeep

Now the "images" folder will be included in your repository, even though it's technically empty.

Understanding Git Submodules

Submodules let you include one Git repository inside another. This is helpful when you need to use external code but want to keep it separate.

What Are Submodules Good For?

• Including libraries or frameworks in your project
• Separating a large project into smaller parts
• Keeping shared code in one place while using it in multiple projects

Adding a Submodule

# Add a submodule to your repository
git submodule add https://github.com/username/repository.git path/to/submodule

# Example:
git submodule add https://github.com/jquery/jquery.git libs/jquery

This creates a new folder containing the submodule, and a .gitmodules file that keeps track of your submodules.

Getting a Repository with Submodules

When you clone a repository that contains submodules, you need an extra step to get the submodule content:

# Clone a repository and its submodules in one step
git clone --recurse-submodules https://github.com/username/repository.git

# Or, if you already cloned without the submodules:
git submodule init
git submodule update

Branching: Working on Different Features

Branches allow multiple people to work on different parts of a project without interfering with each other.

Basic Branch Commands

# Create a new branch
git branch new-feature

# Switch to a branch
git checkout new-feature

# Create and switch in one command
git checkout -b new-feature

# See all branches (the current one has an asterisk)
git branch

Common Branching Approaches

1. Main/Development Model:

   • main branch: Always contains stable, working code
   • develop branch: Where new features are combined before they're stable enough for main
   • Feature branches: Where individual new features are developed

2. Feature Branch Workflow:

   • Create a new branch for each feature or bug fix
   • Work on your changes in that branch
   • When finished, create a pull request to merge your branch
   • After review, merge the branch back to the main branch

Basic Git Workflow

Here's a typical workflow when making changes to a repository:

1. Get the latest version from the remote repository:

   git pull origin main

2. Create a branch for your new feature or fix:

   git checkout -b my-new-feature

3. Make your changes to the files in your project

4. Check which files you've changed:

   git status

5. Review your specific changes:

   git diff

6. Add files to the staging area (prepare them for committing):

   # Add specific files
   git add filename.js another-file.css
   
   # Add all changed files
   git add .

7. Commit your changes with a descriptive message:

   git commit -m "Add login form and validation"

8. Push your changes to the remote repository:

   git push origin my-new-feature

9. Create a pull request on GitHub to merge your changes into the main branch

Helpful Git Commands Explained

Basic Commands

# Download a repository from GitHub to your computer
git clone https://github.com/username/repository.git

# See which files have changed
git status

# Add a file to the staging area (preparing for a commit)
git add filename.js

# Save your staged changes as a new commit
git commit -m "Brief description of what you changed"

# Send your commits to GitHub
git push

# Get the latest changes from GitHub
git pull

Fixing Mistakes

# Undo changes in a file that you haven't staged yet
git checkout -- filename.js

# Unstage a file (remove from staging area, but keep your changes)
git reset HEAD filename.js

# Change your last commit message
git commit --amend -m "New message"

# Undo your last commit but keep the changes for editing
git reset --soft HEAD~1

# Completely discard your last commit and all changes
git reset --hard HEAD~1

GitHub-Specific Features

Pull Requests

Pull requests are how you propose changes to a repository:

1. Make your changes in a branch
2. Push the branch to GitHub
3. On GitHub, click "Compare & pull request"
4. Add a title and description explaining your changes
5. Click "Create pull request"
6. Wait for others to review your changes
7. Once approved, the changes can be merged

GitHub Actions

GitHub Actions automate tasks when certain events happen in your repository (like when someone pushes code or creates a pull request).

Example uses:

• Running tests automatically when code is pushed
• Deploying your application when changes are merged to the main branch
• Publishing packages when you create a new release

Actions are defined in YAML files stored in the .github/workflows/ directory.

GitHub Pages

GitHub Pages lets you host websites directly from your repository:

1. Create a repository named yourusername.github.io
2. Push your website files to this repository
3. Visit yourusername.github.io to see your site

You can also host project-specific sites from a gh-pages branch or a docs/ folder in any repository.

Best Practices for Collaboration

Writing Good Commit Messages

A good commit message clearly explains what changed and why:

Add login form validation

- Check that email addresses are valid
- Ensure passwords are at least 8 characters
- Show user-friendly error messages

Making Effective Pull Requests

1. Keep changes focused: Each pull request should address one specific feature or fix
2. Write clear descriptions: Explain what you changed and why
3. Include screenshots if you made visual changes
4. Link to related issues: Use phrases like "Fixes #123" to link to issues

Code Review Tips

When reviewing someone else's code:

1. Be kind and constructive
2. Ask questions rather than making demands
3. Explain why you're suggesting changes
4. Look for both bugs and improvements

Resolving Merge Conflicts

Merge conflicts happen when two people change the same part of the same file. To fix them:

1. Pull the latest changes from the main branch
2. Git will show you which files have conflicts
3. Open those files and look for sections marked with <<<<<<< HEAD, =======, and >>>>>>> branch-name
4. Edit the files to resolve the conflicts (decide which changes to keep)
5. Save the files
6. Stage the resolved files with git add
7. Complete the merge with git commit

Repository Maintenance

Keeping Your Repository Clean

1. Delete old branches after they've been merged
2. Use clear, consistent file names
3. Document your code with comments and README updates

Updating Dependencies

Regularly update external libraries and packages used in your project to get bug fixes and security updates.

Troubleshooting Common Issues

"I committed to the wrong branch!"

# Save your changes to a new branch
git branch new-branch-name

# Go back to where you should have been
git checkout correct-branch

# Merge your changes from the new branch
git merge new-branch-name

"I need to undo my last push!"

Be careful with this, as it rewrites history:

# Undo the last commit locally
git reset HEAD~1

# Force push to update the remote repository
git push -f origin branch-name

"My pull/push was rejected!"

This usually means someone else pushed changes while you were working. Fix it with:

# Get their changes
git pull origin branch-name

# Resolve any conflicts
# Then push your changes
git push origin branch-name

Conclusion

Git and GitHub have many features to help teams work together effectively. Start with these basics, and as you get more comfortable, you can explore more advanced techniques to improve your workflow.

Remember that everyone makes mistakes with Git, even experienced developers. Don't be afraid to experiment—you can always ask for help or look up commands when you need to.