But despite how central the terminal is to developer workflows, AI assistance there has remained shallow: autocomplete a command here, explain an error there.

That changes when you combine GitHub Copilot CLI with MCP (Model Context Protocol) servers. Instead of an AI that reacts to isolated prompts, you get a terminal that understands your project context, queries live data sources, and chains tool calls autonomously – what the industry is starting to call an agentic workflow.

In this tutorial, you'll learn exactly how to wire these two systems together, step by step. By the end, your terminal will be able to do things like understand your Git history before suggesting a fix, query your running Docker containers before writing a compose patch, or pull live API schemas before generating a request.

Table of Contents

• Prerequisites

• What is GitHub Copilot CLI?

• What is the Model Context Protocol?

• How MCP Servers Work in a Terminal Context

• Step 1 – Install and Configure GitHub Copilot CLI

• Step 2 – Set Up Your First MCP Server

• Step 3 – Wire Copilot CLI to Your MCP Server

• Step 4 – Build a Real Agentic Workflow

• Step 5 – Extend with Multiple MCP Servers

• Debugging Common Issues

• Conclusion

Prerequisites

Before you start, make sure you have the following:

• Node.js v18 or later (node --version)

• npm v9 or later

• A GitHub account with Copilot enabled. The free tier (available to all GitHub users) is sufficient to follow this tutorial. Pro, Business, and Enterprise plans unlock higher usage limits but aren't required.

• GitHub CLI (gh) installed. We'll use it to authenticate.

• Basic familiarity with the terminal and JSON configuration files

• (Optional) Docker installed if you want to follow the Docker MCP example in Step 5

You don't need prior experience with MCP or agentic AI systems, as this guide builds that understanding from the ground up.

What is GitHub Copilot CLI?

GitHub Copilot CLI is the terminal-native interface to GitHub's Copilot AI. Unlike the IDE plugin (which assists with code completion), Copilot CLI is designed specifically for shell workflows. It exposes three main commands:

• gh copilot suggest proposes a shell command based on a natural language description

• gh copilot explain explains what a given command does

• gh copilot alias generates shell aliases for Copilot subcommands

Here's a quick example of suggest in action:

gh copilot suggest "find all files modified in the last 24 hours and larger than 1MB"

Copilot will return something like:

find . -mtime -1 -size +1M

It will also ask if you want to copy it, run it directly, or revise the request. This interactive loop is already useful – but by itself, Copilot CLI has no awareness of your project context. It doesn't know your repo structure, your running services, or your deployment environment. That's where MCP comes in.

What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard introduced by Anthropic in late 2024. Its goal is straightforward: give AI models a standardized way to connect to external tools, data sources, and services.

Think of MCP as a universal adapter layer between an AI model and the real world. Without MCP, each AI integration is custom-built: one plugin for GitHub, another for Postgres, another for Slack, all with incompatible interfaces. MCP defines a single protocol that any tool can implement, and any compatible AI client can consume.

An MCP server exposes tools (functions the AI can call), resources (data the AI can read), and prompts (reusable instruction templates). The AI client in our case, a Copilot-powered terminal discovers these capabilities at runtime and uses them autonomously to complete a task.

A few notable MCP servers that are already production-ready:

The full registry lives at github.com/modelcontextprotocol/servers.

How MCP Servers Work in a Terminal Context

Before we get hands-on, it's worth understanding the communication model.

MCP servers run as local processes. They communicate with the AI client over stdio (standard input/output) or over an HTTP/SSE transport. The client sends JSON-RPC messages to the server, and the server responds with structured data.

Here's the simplified flow:

The key word here is grounded. Without MCP, Copilot responds based purely on its training data and your prompt. With MCP, it can call git log --oneline -20 before answering your question about recent regressions and its answer is based on your actual code history, not a generalized assumption.

Step 1 – Install and Configure GitHub Copilot CLI

If you haven't already, install the GitHub CLI:

# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Windows (via winget)
winget install --id GitHub.cli

Then authenticate:

gh auth login

Follow the interactive prompts. Select GitHub.com, then HTTPS, and authenticate via browser when prompted.

Now install the Copilot CLI extension:

gh extension install github/gh-copilot

Verify the installation:

gh copilot --version

You should see output like gh-copilot version 1.x.x.

Optional but recommended: set up shell aliases. This makes the workflow much faster. For bash or zsh:

# Add to your ~/.bashrc or ~/.zshrc
eval "$(gh copilot alias -- bash)"   # for bash
eval "$(gh copilot alias -- zsh)"    # for zsh

After reloading your shell (source ~/.bashrc), you can use ghcs as shorthand for gh copilot suggest and ghce for gh copilot explain.

Step 2 – Set Up Your First MCP Server

We'll start with server-git. It's the most immediately useful for a development workflow and has zero external dependencies.

Install it globally via npm:

npm install -g @modelcontextprotocol/server-git

Test that it runs:

mcp-server-git --version

This server exposes the following tools to any compatible MCP client:

• git_log retrieve commit history with filters

• git_diff diff between branches or commits

• git_status current working tree status

• git_show inspect a specific commit

• git_blame annotate file lines with commit info

• git_branch list or switch branches

Now create a configuration file. MCP clients look for a file called mcp.json to discover available servers. Create it in your project root or in a global config directory:

mkdir -p ~/.config/mcp
touch ~/.config/mcp/mcp.json

Add the following content:

{
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--repository", "."],
      "transport": "stdio"
    }
  }
}

A few notes on this config:

• command is the binary to run. Make sure it's on your $PATH.

• args passes --repository . so the server scopes itself to the current working directory.

• transport: "stdio" means communication happens over standard input/output the simplest and most stable option for local servers.

Step 3 – Wire Copilot CLI to Your MCP Server

This is where the two systems connect. GitHub Copilot CLI supports MCP via its --mcp-config flag (available from version 1.3+). You point it at your mcp.json, and Copilot will automatically initialize the declared servers before processing your prompt.

Here's the basic invocation:

gh copilot suggest --mcp-config ~/.config/mcp/mcp.json "why did the build break in the last commit?"

When you run this inside a Git repository, Copilot CLI will:

1. Start the mcp-server-git process

2. Call git_log to retrieve recent commits

3. Call git_diff on the most recent commit

4. Synthesize an answer based on the actual diff output

Try it yourself on a repo with a recent failing commit. The difference in response quality compared to a plain gh copilot suggest is immediately obvious.

Tip: avoid retyping the flag every time. Add a shell function to your .bashrc/.zshrc:

function aterm() {
  gh copilot suggest --mcp-config ~/.config/mcp/mcp.json "$@"
}

Now you just type:

aterm "what changed between main and feature/auth?"

And you're running a fully context-aware, MCP-powered query from a single short command. This function name aterm for agentic terminal is what we'll use throughout the rest of this tutorial.

Step 4 – Build a Real Agentic Workflow

Let's move beyond individual queries and build a workflow that chains multiple tool calls to complete a real developer task: diagnosing a regression.

Imagine you pushed a feature branch and your CI pipeline failed. You don't know exactly which change caused it. Here's how your agentic terminal handles it:

Query 1: understand what changed

aterm "summarize all commits on feature/auth that aren't on main yet"

Copilot calls git_log with branch filters, then returns a structured summary of commits unique to your branch. No copy-pasting SHAs manually.

Query 2: isolate the diff

aterm "show me everything that changed in the auth middleware between main and feature/auth"

This triggers git_diff scoped to the path containing your middleware. Copilot returns the diff with an explanation of what each change does.

Query 3: find the likely culprit

aterm "which of those changes could cause a JWT validation failure?"

At this point, Copilot has the diff in its context window from the previous tool calls. It reasons over the actual code changes not generic knowledge about JWT and pinpoints the likely issue.

Query 4: generate the fix

aterm "write the corrected version of that validation function"

Copilot generates a targeted fix based on the specific code it retrieved via MCP. You get a patch you can directly apply, not a generic code template.

This four-step sequence – understand, isolate, reason, fix – is a complete agentic loop. Each step is grounded in live repository data retrieved through MCP tools. The AI is not hallucinating context. Instead, it's reading your actual codebase.

Step 5 – Extend with Multiple MCP Servers

One MCP server is useful. Multiple MCP servers working together is where the workflow becomes genuinely powerful. Let's add two more: server-filesystem and server-docker.

Install the additional servers:

npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-docker

Update your mcp.json:

{
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--repository", "."],
      "transport": "stdio"
    },
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["--root", "."],
      "transport": "stdio"
    },
    "docker": {
      "command": "mcp-server-docker",
      "transport": "stdio"
    }
  }
}

With all three servers active, your terminal can now answer cross-domain questions:

aterm "my Express app container keeps restarting, check the logs and compare with what the healthcheck in my Dockerfile expects"

To answer this, Copilot will:

1. Call docker_logs (server-docker) to pull the container's recent stderr output

2. Call read_file (server-filesystem) to read your Dockerfile

3. Parse the HEALTHCHECK instruction

4. Cross-reference the log errors with the health endpoint path

5. Return a diagnosis explaining the mismatch and suggest the fix

This is an agentic workflow: the model autonomously decides which tools to call, in what order, and synthesizes the results into a coherent answer. You didn't tell it to read the Dockerfile. It inferred that was necessary based on your question.

A note on security: When running server-filesystem, always scope it to a specific directory using --root. Never point it at / or your home directory. Similarly, server-docker has access to your Docker socket run it only in trusted environments.

Debugging Common Issues

mcp-server-git: command not found

The npm global bin directory isn't on your $PATH. Fix:

export PATH="\(PATH:\)(npm bin -g)"
# or for newer npm versions:
export PATH="\(PATH:\)(npm prefix -g)/bin"

Add this line to your .bashrc/.zshrc to persist it.

Copilot CLI doesn't seem to be using MCP tools

Check your Copilot CLI version:

gh copilot --version

MCP support requires version 1.3 or later. Update with:

gh extension upgrade copilot

Also verify your mcp.json is valid JSON a trailing comma or missing bracket will silently prevent server initialization.

MCP server starts but returns no data

Run the server manually to check for errors:

mcp-server-git --repository .

If it exits immediately, check that you're running the command inside a valid Git repository. For server-docker, make sure the Docker daemon is running and your user has access to the Docker socket:

sudo usermod -aG docker $USER
# Then log out and back in

Responses are slow with multiple servers

Each MCP server is a separate subprocess. Spawning several at once adds startup latency, especially on slower machines. Two optimizations:

1. Only declare the servers you actually need for a given project in your mcp.json

2. Use project-specific config files instead of one global config:

# project A (backend)
aterm --mcp-config ./mcp-backend.json "..."

# project B (infra)
aterm --mcp-config ./mcp-infra.json "..."

Conclusion

You've just built an agentic terminal workflow from scratch. Here's a quick recap of what you did:

• Installed and configured GitHub Copilot CLI with shell aliases for fast access

• Set up MCP servers (server-git, server-filesystem, server-docker) and wired them through a mcp.json config

• Created a shell function (aterm) that transparently passes your MCP config to every Copilot query

• Built a multi-step agentic loop for diagnosing regressions using live Git data

• Extended the setup with cross-domain tool orchestration across Git, filesystem, and Docker

The architecture you've built here is not a demo – it's a production-ready pattern. You can extend it with any MCP-compatible server: server-postgres for database-aware queries, server-github for issue and PR context, or custom MCP servers you write yourself for your internal APIs.

The terminal has always been the most powerful surface in a developer's environment. With Copilot CLI and MCP, it's finally becoming an intelligent one.

This is a common experience when contributing to open source: you make a small change, open a pull request, and suddenly everything fails.

Not just one check, but multiple:

• Lint errors

• YAML validation issues

• Build failures

• Deployment failures

Even more confusing, you may see errors in parts of the codebase you didn’t modify.

In this article, you'll learn how to debug these issues step by step. The goal is not just to fix one pull request, but to understand how CI systems validate your changes.

This guide is based on a real debugging experience from contributing to an open source documentation project.

While this example comes from a documentation project, the debugging workflow applies to many repositories that use CI pipelines, linting tools, and automated builds.

Table of Contents:

• Understanding the CI Pipeline (What’s Actually Happening)

• How a CI Pipeline Processes Your Pull Request

• A Practical Debugging Workflow

  • Step 1: Fix Authentication and Permission Issues

  • Step 2: Run Lint Checks Locally

  • Step 3: Fix Common Markdown Lint Errors

  • Step 4: Fix YAML Inside Markdown Code Blocks

  • Step 5: Fix Build Errors After Lint Passes

  • Step 6: Debug Cascading CI Failures

  • Step 7: Handle Git Issues During CI Debugging

• Key Takeaways

• Conclusion

Prerequisites

To follow this guide, you should have:

• Basic familiarity with Git and pull requests

• A GitHub account

• Some exposure to CI/CD concepts (helpful but not required)

Understanding the CI Pipeline (What’s Actually Happening)

In many projects, you will see the term CI/CD, which stands for Continuous Integration and Continuous Deployment (or Delivery).

In this guide, we'll focus specifically on the CI part – that is, Continuous Integration. This refers to the automated checks that run when you push code or open a pull request. These checks validate your changes before they're merged into the main codebase.

CD (Continuous Deployment/Delivery), on the other hand, typically handles what happens after those checks pass, such as deploying the application.

Understanding this distinction is important because most of the issues we debug in this guide happen during the CI stage.

Most repositories run multiple automated checks when you open a pull request:

• Linting tools (for example, markdownlint, yamllint) enforce formatting rules

• Build systems (for example, mdBook) validate structure and generate output

• Deployment checks (for example, Netlify) ensure that the site can be built and served

• Merge controllers (for example, Tide) enforce approval policies

A key point to remember: CI systems validate the entire set of files in your commit, not just the lines you changed.

How a CI Pipeline Processes Your Pull Request

When you push code or open a pull request, the CI pipeline runs several checks in sequence.

Let’s visualize how these checks are connected in a typical CI pipeline.

Figure: A simplified CI pipeline showing how linting, build, and deployment checks are executed sequentially.

The above diagram shows a sequential CI pipeline with feedback loops, where failures at any stage return you to fix the issue before continuing.

Let’s break down what this diagram shows:

1. You start by pushing code or opening a pull request.

2. The CI pipeline begins running automated checks.

3. The first set of checks typically includes linting tools like markdownlint or yamllint.

   • If linting fails, the pipeline stops, and you must fix formatting issues before continuing.

   • If linting passes, the pipeline moves to the build step (for example, mdBook in documentation projects).

   • If the build fails, it usually means there is a structural issue, such as duplicate entries or invalid references.

4. After a successful build, deployment checks (such as Netlify previews) run.

   • If deployment fails, the issue is often related to configuration or build output.

5. If all steps pass, the pull request becomes ready for review.

A Practical Debugging Workflow

Step 1: Fix Authentication and Permission Issues

Before CI runs, your push can fail due to authentication errors.

Example error:

refusing to allow a Personal Access Token to create or update workflow

This happens because GitHub requires special permissions when your commit includes files under:

.github/workflows/

The solution is to regenerate your Personal Access Token (PAT) with:

• repo access

• workflow permission

Step 2: Run Lint Checks Locally

Relying only on CI feedback slows you down because you have to push changes and wait for the pipeline to run before seeing errors.

Running checks locally allows you to catch issues immediately before pushing your code.

In practice, you should do both:

• Run checks locally to catch errors early and reduce iteration time

• Use CI as the final validation to ensure your changes meet the repository’s standards

Think of local checks as your first line of defense, and CI as the final gate before your code is accepted.

Here's an example (Markdown linting):

npm install -g markdownlint-cli2
markdownlint-cli2 docs/**/*.md

Step 3: Fix Common Markdown Lint Errors

Here are some common issues you may encounter:

1. Non-descriptive links

Non-descriptive links like "here" don't give readers any context about where the link leads. This makes documentation harder to understand and less accessible, especially for users relying on screen readers.

Instead of writing:

[here](https://example.com)

Use descriptive text like:

[command help documentation](https://example.com)

2. Line length violations

Many projects enforce a maximum line length (often around 80 characters) to improve readability across different devices and editors.

If a line is too long, you can split it into multiple lines without changing the meaning.

To do this, break the line at natural points such as spaces between words or after punctuation. Avoid breaking words or disrupting the sentence structure.
For example:

This is a long sentence that should be split across multiple
lines to satisfy lint rules.

3. List indentation issues

List indentation errors occur when nested list items aren't aligned consistently. This can break formatting and cause linting errors.

To avoid this, just make sure you use consistent spacing (usually 2 spaces per level).

Example (incorrect):

- Item 1
 - Subitem

Correct version:

- Item 1
  - Subitem

Step 4: Fix YAML Inside Markdown Code Blocks

YAML has strict formatting rules, including proper indentation, key-value structure, and consistent spacing.

Even when YAML appears inside a markdown code block, tools like yamllint still validate its structure.

Example (incorrect):

metadata:
annotations:

Correct version:

metadata:
  annotations:
    capi.metal3.io/unhealthy: "true"

In the incorrect example, annotations is not properly nested under metadata, and no key-value pair is defined.

In the corrected version:

• annotations is properly indented under metadata

• a valid key-value pair is added (capi.metal3.io/unhealthy: "true")

This structure satisfies YAML’s requirement for proper hierarchy and formatting.

Step 5: Fix Build Errors After Lint Passes

Passing lint checks doesn't guarantee that your build will succeed.

This is because linting focuses on syntax and formatting, while the build process validates the structure and integrity of the entire project.

Build failures often occur due to issues such as:

• Duplicate entries in navigation files

• Missing or incorrectly referenced files

• Invalid configuration settings

Even if your syntax is correct, the build system ensures everything connects properly.

For example, in documentation projects using tools like mdBook, a duplicate entry in SUMMARY.md can cause the build to fail even when all files pass lint checks.

Step 6: Debug Cascading CI Failures

CI pipelines are layered. One failure can trigger multiple downstream failures.

For example, imagine a YAML indentation error:

YAML error → build fails → deploy fails → multiple checks fail

To fix this:

1. Identify the first failing step in the CI logs

2. Fix that issue

3. Re-run the pipeline

In this example, the YAML indentation error is the root cause. Once you fix the YAML formatting, the lint check passes, which allows the build to proceed and the deployment step to succeed.

This is why it is important to always fix the first failure in the pipeline rather than trying to address all errors at once.

Step 7: Handle Git Issues During CI Debugging

When working with updated branches, you may encounter:

• Diverged branches

• Rebase conflicts

• Push rejections

To resolve these issues, you typically need to update your branch using one of two approaches:

Option 1: Rebase (clean history)

git pull --rebase

Rebasing rewrites your commit history so your changes appear on top of the latest version of the branch.

Use carefully:

• Only rebase your own branches

• Avoid rebasing shared branches

Option 2: Merge (safer)

git pull --no-rebase

Merging preserves the full commit history and is safer when working with others, but it may introduce additional merge commits.

Pushing your changes safely

After updating your branch, you may need to push changes:

git push --force-with-lease

Avoid using:

git push --force

The --force option can overwrite the other contributors’ work. The --force-with-lease option is safer because it only pushes if the remote branch has not changed unexpectedly.

Key Takeaways

• CI validates your entire commit, not just the specific lines you changed

• Linting and build systems enforce different rules

• YAML inside markdown must be structurally correct

• Documentation builds can fail due to structural issues

• Running checks locally significantly reduces debugging time

Conclusion

Debugging a failing pull request isn't just about fixing syntax errors.

You also need to understand how different systems interact:

• Version control

• CI pipelines

• Linting tools

• Build processes

Once you understand how these systems work together, you can debug issues systematically instead of guessing.

The next time your pull request fails, you will know exactly where to start and how to fix it.

Debugging CI issues may feel overwhelming at first, but with a structured approach, you can turn failures into a clear path for improvement.

But beyond repositories and commits, your profile can say a lot about you as a developer.

When used intentionally, GitHub becomes more than a code hosting platform. It becomes your CV for your codebase. It tells your story, showcases your skills, and gives people a reason to trust your work.

In this article, we'll break down the different ways to make your GitHub profile stand out. From setting up your GitHub account to engaging storytelling for your repositories, there's lots you can do.

Let's get started!

Table of Contents

• Sign Up for a Github Account

• Add a Profile Image

• Add Profile Details

• Add a Profile README File

• Tell a Story About Each Repository

Step 1: Sign Up for a Github Account

To begin, you'll need a GitHub account. If you don’t have one, you can set one up here.

Once you have your account set up and you're logged in, we can move on to the next step.

Step 2: Add a Profile Image

Your profile image is often the first thing people notice. It could be a professional photo of yourself, or an image or avatar that represents you or your interests

As long as it’s appropriate, you’re good to go.

To add a profile image, you'll need to:

• Open your profile menu/dashboard

• Click on the image icon at the left

• Click on the edit text on the image icon

• Select the image to set as your profile picture

• Click the "Set new profile picture" button

So, you should have something like this:

GitHub link to this page: https://github.com/settings/profile

And there you have it, your GitHub profile image is set.

On to the next one…

Step 3: Add Profile Details

This step is all about credibility and discoverability.

At the center of your profile settings you'll see fields like email, location, social media links and so on. We'll be adding those details so you can take advantage of the discoverability it lends to your profile.

GitHub link to this page: https://github.com/settings/profile

For this step, you'll want to add as much detail as possible (apart from your home address – I think we both know why).

For the location, you can just put in your city or country so others have a general idea of where you are in the world.

Step 4: Add a Profile README File

This is where you introduce yourself properly and tell your story.

A Profile README is a special repository named exactly the same as your GitHub username. Your README file appears directly on your profile page.

The READme should answer the following questions:

• Who are you?

• What are your project highlights?

• What are you currently working on or learning?

• Your hobbies or interests (optional)

While answering these questions, you should aim to keep it minimal and yet interesting. You don't want to overwhelm the visitor.

Here's how to create your README:

• Click New repository

• Name the repository exactly the same as your GitHub username

• Check “Add a README file”

• Make sure the repository is public

• Click Create repository

Profile README file setup:

GitHub link to this page: https://github.com/new

So if you answered the questions listed above, your README file should look something like this:

GitHub link to this page: https://github.com/chinazachisom/chinazachisom

It should also be showing directly on your GitHub profile like below:

GitHub link to this page: https://github.com/chinazachisom

Step 5: Tell a Story About Each Repository

Now, this is where you can tell a story about each of your repositories using a README file.

NB: Each repository should have its own separate README file.

What to include in a repository README:

• Project title

• What the project is

• The purpose (the “why”)

• Key features

• Challenges you faced and how you solved them

• Setup or usage instructions (or a live link if hosted)

• Technical concepts used (e.g., throttling, caching, lazy loading) (optional)

• Images or video demos

You may also include badges, charts, contribution graphs or other visual enhancements that help highlight project quality, activity and impact.

With the above structure, you can tell the stories behind your projects, show your problem-solving skills, and make your work easier to understand and evaluate.

Repository README File Sample:

GitHub link to this page: https://github.com/chinazachisom/Artsy

Conclusion

Your Github Profile is more than just a storage space for your codebase. It's your developer Identity as well.

Following these basic steps can help turn your Github into a portfolio infused with your personal brand. It makes your GitHub Profile stand out, which can help open doors for more opportunities.

Treat it like a CV for your code and let your work speak for you.

About the Author

Hi there! I'm Chinaza Chukwunweike, a Software Engineer passionate about building robust, scalable systems that make a real world impact. I'm also an advocate for continuous learning and improvement.

If you found this useful, please share it! And follow me for more Software Engineering tips, AI learning strategies, and productivity frameworks.

I didn't want to just add Claude Code to my stack. I actually wanted to replace Copilot entirely for two weeks. I kept everything else the same – same editor, same projects, same workflow. I just swapped the autocomplete suggestion tool.

Here's what broke, what improved, and whether I went back.

Table of Contents

• The Setup

• What Worked Better

• What Broke (Or Slowed Things Down)

• The First Week vs The Second Week

• Why I Went Back

• The Honest Verdict

• What I Actually Use Now

• Copilot vs Claude Code — The Breakdown

• A Word on Developer Experience

• What Would Make Me Switch

• Final Thoughts

The Setup

Environment:

• Python 3.12 for backend work (Django REST framework specifically)

• React/TypeScript for frontend

• VSCode as my editor

• A mid-sized project with about 15k lines of code across backend and frontend

• Two weeks, normal workload (roughly 30-40 hours of coding)

• Working on features I'd normally tackle: adding endpoints, debugging issues, writing tests

What I did:

• Disabled GitHub Copilot completely. Uninstalled the extension.

• Set up Claude Code (via their CLI and VSCode integration).

• Kept everything else identical: same repos, same Git flow, same daily work.

• Tracked time on each task to see if there was a real difference.

Ground rules:

• I couldn't use Copilot as a fallback. This was an honest comparison.

• I logged every time I got frustrated or felt like Claude Code was slowing me down.

• I kept track of bugs I caught vs. bugs I missed.

The goal: Does Claude Code work as a day-to-day replacement for Copilot, or does it force me back?

What Worked Better

Accuracy

Copilot sometimes suggests things that are close but not quite right. It might finish a regex pattern 80% correctly, and I have to tweak it. It happens maybe 20% of the time.

Claude Code was more accurate. In the first week, I noticed fewer "close but wrong" suggestions. When I typed a function signature, Claude got the implementation right more often than Copilot did.

One example: I was writing a utility to parse JSON and handle errors. Copilot suggested:

def parse_json(data):
 try:
 return json.loads(data)
 except:
 return None

That's sloppy. It catches all exceptions and silently fails.

Claude Code suggested:

def parse_json(data):
 try:
 return json.loads(data)
 except json.JSONDecodeError as e:
 logging.error(f"Failed to parse JSON: {e}")
 return None
 except Exception as e:
 logging.error(f"Unexpected error: {e}")
 raise

Better error handling. More production-ready. That's a real difference.

I estimate Claude Code's suggestions were "immediately usable" about 85% of the time. Copilot was more like 70%.

Understanding Context

Claude Code seems to understand your project better than Copilot. When I opened a file with Claude Code context, it knew:

• My project's naming conventions (I use fetch_ for async functions, get_ for sync).

• My error handling style.

• What libraries I was using.

Copilot sometimes forgot these patterns or suggested things using the wrong library. Claude Code was more consistent.

One morning I was adding a new endpoint to an existing API. I typed the route signature:

@app.post("/api/users")
async def create_user(data: UserPayload):

Copilot might suggest:

 response = requests.post(...)

(Wrong! That's sync. This function is async.)

Claude Code suggested:

 async with httpx.AsyncClient() as client:
 response = await client.post(...)

It remembered that the entire codebase uses async/await and httpx for async calls. That's attention to detail.

Reasoning About Requirements

Sometimes Copilot just completes code. It doesn't think about whether it makes sense.

Claude Code seemed to reason about whether the suggestion was actually what you wanted. A few times, when I was writing ambiguous code, Claude Code offered a clarifying suggestion instead of just finishing it.

Example: I started a function for sorting users:

def sort_users(users):

Copilot would auto-complete with some sorting logic, but I'd have to check if it was what I meant.

Claude Code would sometimes suggest:

def sort_users(users, key="created_at", reverse=False):

It was thinking: "Sorting is ambiguous. What key? What order?" It was right more often than not.

What Broke (Or Slowed Things Down)

Response Time

This was the biggest issue. Copilot is instant. I type def get_ and it finishes before I can blink. It's autocomplete, and autocomplete needs to be fast. The latency is maybe 100-200ms.

Claude Code has a noticeable delay. Maybe 1-2 seconds before suggestions appear. On day one, that felt fine – I had time to think. By day two, I was annoyed. By day three, I was genuinely frustrated.

Over a day of coding, that adds up. If you're typing 20 functions and each one has a 2-second delay, that's 40 seconds of just waiting. It doesn't sound like much, but it breaks flow. Flow is where the good coding happens.

By day three, I was getting frustrated. I'd type faster than Claude Code could suggest, which meant I'd often just finish the code myself. The second a suggestion appeared, I'd already moved on. Defeating the purpose.

I tested this by tracking time. Same function, same complexity:

• With Copilot: 3 minutes (including auto-complete time)

• With Claude Code: 5 minutes (waiting for suggestions + finishing manually)

The delay isn't theoretical. It's real and measurable.

The truth: Copilot is an autocomplete tool. It needs sub-second latency. Claude Code, being more powerful, is inherently slower. That's a fundamental tradeoff. You can't have both "instant" and "smart." Choose one.

No Inline Acceptance

With Copilot, I press Tab to accept. It's in my muscle memory. Tab = accept.

Claude Code doesn't work exactly the same way. I had to click or use a different keyboard shortcut. Small thing, but it broke my rhythm constantly. I'd write code, see a suggestion, and instinctively press Tab. Nothing would happen. Then I'd remember: "Oh right, it's a different tool."

After two weeks, I never fully got used to it.

Disconnected From Flow

Copilot is so embedded in the editor that I don't think about it. It's just there, like spellcheck. Claude Code feels like a separate tool I'm using, which means I'm more aware of it. That sounds like a good thing, but it's actually more cognitively expensive.

I wanted to type and have suggestions appear. Instead, I felt like I was using a tool. There's a difference. It's the same difference between walking and thinking about walking. When you're thinking about your walking mechanics, you walk worse.

This affected my productivity more than I expected. On day three, I found myself just typing manually instead of waiting for suggestions. It wasn't a conscious decision. I'd just start typing and then remember "oh, the suggestion came in." By then I'd already finished half the function myself.

Limited to the File

Copilot understands your entire project. It knows what's in other files, what libraries you import, what conventions you follow. If I'm importing a utility function that doesn't exist yet, Copilot knows to suggest the import with the path I'd use.

Claude Code seemed more limited to the current file. Sometimes it would suggest imports that weren't already in the file, or use patterns different from the rest of my codebase. Not often, but enough to notice. On one occasion, it suggested a database query pattern that was different from my whole codebase. It would've worked, but it would've been inconsistent.

This is less of a limitation and more of a design difference. Claude Code is built for depth on individual files, not breadth across a project.

The First Week vs The Second Week

Week 1: I was excited. Claude Code felt smarter. I noticed the accuracy advantage. But the latency was starting to annoy me.

Week 2: The novelty wore off. The latency was more annoying. I was missing Copilot's speed. I found myself disabling Claude Code's suggestions and typing manually more often, which defeated the purpose. "If I'm typing it all manually anyway, why switch?"

By day 10, I was typing code faster with Claude Code disabled than with it enabled. That's when I knew it wasn't working for me.

Why I Went Back

On day 14, I re-enabled Copilot.

The first thing I noticed: speed. Code was completing again instantly. My rhythm came back. I hit Tab, it accepted, I moved on. That's the entire appeal of Copilot-it's frictionless.

I also realized how much I'd been manually typing. On days 10-14, I was writing more code by hand because the suggestions felt too slow to be worth waiting for. Without realizing it, I'd completely stopped using Claude Code's suggestions. I was just typing. That's the worst of both worlds: no AI help and the cognitive burden of being aware you're using a tool that's not helping.

Was I sacrificing accuracy? A little. But I'm accurate enough that I catch mistakes in review. For day-to-day, Copilot is fine.

The second thing: it just works. No weird setup, no integration issues. It's part of VSCode. It's always there.

By day 15, I was back to normal productivity, maybe even higher because the flow was better.

The Honest Verdict

Claude Code isn't a Copilot replacement. It's not worse. It's different. It's like comparing a calculator to a calculator app on your phone. One is designed for speed and muscle memory. One is designed to be a full computer in your pocket. They're not competitors.

If I'd tried Claude Code expecting it to be better at debugging, I would've been happy. I was trying it expecting it to replace my autocomplete, which is where it falls flat.

The experiment was valuable, though. It taught me that:

1. Latency matters more than I expected. A 2-second delay breaks flow.

2. Familiarity matters. Tab to accept is burned into my muscle memory.

3. Tool stacking works. Claude Code is great for debugging. Copilot is great for autocomplete. Together they're better than either alone.

What I Actually Use Now

I didn't abandon Claude Code. I just changed how I use it.

• Claude Code: For debugging, analysis, and big changes. "Why is this function slow?" "Refactor this for readability." I invoke it deliberately when I need thinking, not continuous autocomplete.

• Copilot: For routine coding. Finishing functions, auto-completing imports, normal flow.

That's the working solution. Claude Code is powerful, but it's not a Copilot replacement for daily work. It's a different tool for a different use case.

Copilot vs Claude Code: The Breakdown

Copilot is better for:

• Pure autocomplete speed

• Routine, well-understood coding

• Low friction, high flow state

• Simple suggestions

Claude Code is better for:

• Complex suggestions that require reasoning

• Debugging and analysis

• Understanding intent (not just completing code)

• Asking questions about code you've written

If you're a Copilot user thinking about switching, don't do it as a straight replacement. Claude Code isn't faster. It's smarter, but slower, and for day-to-day autocomplete, faster wins.

Try using both. Use Copilot for normal coding, Claude Code for debugging and complex changes. If you only want to pay for one, stick with Copilot. It's cheaper, it's faster, and it does the job.

If you're a heavy debugger and you spend a lot of time analyzing code, Claude Code might be worth it. But as a Copilot replacement? No.

A Word on Developer Experience

What surprised me wasn't just the latency. It was how much I missed the seamlessness of Copilot. With Copilot, I don't think about it. It's like breathing-automatic. I type, it suggests, I accept or reject, I move on.

With Claude Code, I was constantly aware I was using a tool. I'd finish typing before the suggestion appeared. I'd have to remember the keyboard shortcut. I'd have to context-switch to look at the suggestion.

That awareness is exhausting. It's why flow state is so important to programming. The best tools get out of your way. Copilot gets out of the way. Claude Code, for autocomplete purposes, doesn't.

Developer experience isn't a nice-to-have. It's core to productivity. A tool that's 10% smarter but 50% more annoying is worse, not better.

What Would Make Me Switch

• Claude Code needs to get faster. Sub-second latency for suggestions.

• It needs better editor integration. Tab to accept, like Copilot.

• It needs to understand the full project, not just the current file.

Once those three things happen, it'd be competitive. Until then, Copilot is still the better choice for daily coding work.

Final Thoughts

This experiment taught me something: better isn't always better. Claude Code is arguably smarter than Copilot. But Copilot is more efficient. For autocomplete, efficiency matters more than intelligence.

It's like comparing a sports car to a Jeep. The sports car is faster on a highway. The Jeep is better on a mountain trail. Neither is "better." They're different. Copilot is trying to predict the next line of code fast. Claude Code is trying to understand your code deeply. They're solving different problems.

I went back to Copilot not because Claude Code is bad. It's actually impressive. But it's a different category of tool. Using it for autocomplete is like using a hammer when you need a screwdriver. The hammer might be fancier, but the screwdriver does the job.

What surprised me most was how much latency matters. I didn't expect a 2-second delay to be that noticeable. But when you're in the zone, typing code, and the autocomplete lags, it completely breaks your flow. It's not about the absolute time. It's about the interruption.

Don't take my word for it though. Run your own two-week experiment. Pick a tool, commit to it, and see what happens. Track your productivity. Track your frustration. The best tool is the one you'll actually use. And you can only find that out by using it.

What's Next?

If you found this useful, I write about Docker, AI tools, and developer workflows every week. I'm Balajee Asish - Docker Captain, freeCodeCamp contributor, and currently building my way through the AI tools space one project at a time.

Got questions or built something similar? Drop a comment below or find me on GitHub and LinkedIn.

Happy building.

Curious about the hype I saw on Bluesky, I recently joined the npmx Discord server on a whim. My journey from lurker to contributor taught me a lot about OSS and gave me new confidence going into code reviews.

In this article, I’ll walk you through my journey to give you a little insight into the process of getting involved in Open Source.

Here’s what I’ll cover:

• My Struggles with Pull Requests

• My Former View of OSS

  • The Basics of OSS

  • The Dark Side of OSS

• Getting Started with npmx

• The Not So Perfect PR

• Collaboration Over Perfection

• My Current View of OSS

• Tips for PR Authors and Reviewers

• Conclusion

My Struggles with Pull Requests

I’ll admit, I’ve always had a hard time with code reviews. I can be quite the perfectionist. I’ll entertain every nitpick and only hear the criticism.

If reviews go on for days, I easily get overwhelmed. I enjoy pairing and co-working. I want to enjoy Pull Request (PRs), but addressing PR comments takes a lot out of me.

Some of my struggle is a need for accommodations that I rarely get. I also have plenty of lived experience with how hostile code reviews can become (even in a professional setting). Finally, there’s how I was introduced to PR reviews.

Outside of work, I had only ever experienced perfunctory PRs – I’d receive at most one suggestion, but usually just got a “LGTM” (Looks Good to Me) comment. Professionally, I went from no code reviews to incredibly detailed code reviews basically overnight. I still feel like I’m playing catch up.

On the one hand, thinking deeply about every suggestion has made me a better developer. I thrive in collaborative environments with thoughtful code reviews. Developers who have worked with me have told me that they benefit from answering all my “why?” questions.

On the other hand, I demand compliments, gifs, and video calls from my reviewers. I don’t do well with a bombardment of vague comments on my PRs. I’ve spent a lot of time documenting code guidelines and review processes that other people seem to understand and remember much more easily than I do.

Developer communities have helped me navigate all of this. Community is a priceless resource for career changers and new grads. When everyone shares their experience, the uninitiated learn about how things could be and what kinds of things aren’t normal (like very hostile code reviews).

My Former View of OSS

When I’ve talked and written about developer community, I’ve recommended online networking communities, going to meetups, tech conferences, social media, writing, and posting your writing online. The one thing I haven’t written about? OSS.

My first real introduction to OSS was through the online networking group Virtual Coffee. By the end of my first Hacktoberfest, I knew the basics.

The Basics of OSS

• Find a project that interests you.

• Check the Contributing Guide.

• Claim an issue.

• Following the Contributing Guide, make a fork, write the code, and open a PR.

• The maintainer merges it.

• You did it! That’s OSS.

The Dark Side of OSS

Over time, I couldn’t help but see the “dark side” of OSS – maintainers burning out, friction between users and maintainers, corporations suddenly trying to assert control over OSS (for example, Wordpress, Ruby), and the thankless, frustrating job of maintaining a package that everyone uses but no one wants to pay for.

I have to be honest: I had begun to think of open source maintainers as Roz from Monsters Inc. – justifiably fed up with the extra work dumped on them by unappreciative people.

Meeting maintainers in-person didn’t contradict my view. Every single one had a story about burnout and lack of funding. I started to assume that anyone excited about OSS just hadn’t been in it long enough

…so my friends were quite surprised when I suddenly announced that I had joined the OSS project npmx.

Getting Started with npmx

It wasn’t the first mention of the npmx project that interested me. It wasn’t the second. It was a meme. I’ve known Daniel Roe long enough to know that he is brilliant. I like learning from people who are smarter than I am.

I reached out to Patak, and got an invite to the npmx Discord server. I was amazed by what I saw: a rapidly growing, excited, and inclusive community. I realized that I had only ever contributed to communities with at most a handful of people. My view of OSS immediately changed.

This was it. I was finally going to have fun doing PRs.

So I hopped into the npmx GitHub repository and tried to get my bearings. Very quickly, I was overwhelmed. The project moves so fast. I tried to do step 3 – claim a ticket. As far as I could tell, all the tickets were being claimed in Discord before or as they were being written.

Jono kindly welcomed me into his fork for working on the blog page, but I ran into frustrating and weird issues with running the repository (repo) locally and the pre-commit hooks. Multiple people tried to help me debug and were just as stumped as I was.

The next day, Salma arrived. The day after, she was in charge of outreach, and asked me to write a blog. Then life got in the way. I couldn’t keep my promise to context switch into a feature branch in a new repo. I felt like my only contribution was going to be a single line change on the blog page and a blog.

It didn’t help that I wasn’t happy with the blog I had started writing. I gave up on keeping up and lurked in the Discord channels. I chimed in on a few conversations, and offered to help with things like failing accessibility tests.

Four days later, the project was officially two weeks old. The maintainers announced a mandatory week of vacation – community members experienced with burnout had seen the writing on the wall. Vacation would start in 10 days, so that’s basically how long I had to get a contribution in before the alpha release.

The Not So Perfect PR

An hour later, I finally saw it – my chance to contribute code. Alex needed a toggle re-written as a checkbox. It was my time to shine. I commented on the ticket to claim it as soon as it was written. I slapped up a draft PR to show I was working on it. Predictably, my focus was once again pulled away from the repo.

A couple days later, Knowler reviewed my draft PR, and all my PR anxieties came tumbling back. This was going to be The Perfect PR. How dare anyone look at it before I was ready to defend my work. What would they think about my abilities looking at my old copy and pasted portfolio site code that I hadn’t even finished translating from React to Vue? I was legitimately embarrassed someone was looking at my code in that state.

Fueled by embarrassment and productive procrastination, I sprung into action. In what little free time I had, I must have toggled my toggle a thousand times. Three days later, it was finally in a state I was happy with. It was time to open up my PR for review.

A couple dozen comments came in. Overwhelmed, I tried to remember that I had asked for this. I resolved most of the comments and left a comment saying I’d get to the last item, forced colors mode, in the morning. Frustrated with the code for the forced colors and myself for forgetting a few tiny things, I went to play games with friends.

A few hours later, I got a DM from Daniel. He had some code for my PR. I agreed with his reasoning for all the changes and found out an entire tooltip had been added while I was blissfully ignoring the rest of the repo. (I’m confident in my ability to merge or rebase my way out of any situation.)

Splitting my attention between Enshrouded and talking to Daniel, I felt defeated. I knew I finish the forced colors fix the next day, but also adding a tooltip felt daunting. Still, it felt like I needed to do it all.

Collaboration Over Perfection

And then I remembered, this wasn’t work and it wasn’t going to come up on a performance review. I wasn’t alone – Knowler and Daniel were taking the time to help me get this PR merged because they wanted to. I had the opportunity to collaborate with some brilliant people and see how they would write the same thing.

So I pushed through my perfectionism, demanded compliments, and asked Daniel to push his changes. I told him I’d review them in the morning.

Reviewing Daniel’s code, I found that he had forgotten a couple tiny things, just like I had. The code I was frustrated with the night before was legitimately frustrating. Emulating forced colors on a Mac was giving me weird and contradictory results. I needed to test on a Windows machine to finally get it right.

Then, six days after I opened the PR, I finally merged it. I was on top of the world. I had gotten my contribution in before our vacation (and more importantly, I had received multiple compliments). Finally, I knew what to write this blog about.

My Current View of OSS

When you’re looking for a project that interests you, the code isn’t the only thing to evaluate. Early in my career, I learned three rules for evaluating software tools.

1. Check the date of the last update to make sure it’s actively maintained.

2. Look at the documentation. Is it up to date and easy to follow?

3. Check out the community. Do people get fairly quick responses to their questions?

After joining npmx, I’ve discovered that, with a few tweaks, these rules also apply to evaluating an OSS project.

1. Check out the last few tickets and PRs to see how fast the repo moves. If it’s fairly slow, you can probably claim an issue in GitHub easily. If it’s rapid, start by getting to know the community and how they’re assigning tickets.

2. You should always check the repo for a code of conduct, contributing guide, and sufficient documentation. Also evaluate the tickets. Are contributors expected to research solutions on their own or given strict requirements? How do maintainers respond to comments on issues?

3. Check out the community. An active, inclusive community makes contributing a lot more fun.

Now, my view of OSS is much more nuanced. Yes, there are issues with OSS as whole, but there’s a reason people want to fix them. OSS can be collaborative, inspirational, and enjoyable.

Tips for PR Authors and Reviewers

People underestimate the importance of the relationship between PR author and reviewer. A collaborative OSS code review process doesn’t happen in a vacuum. It takes careful cultivation by the PR author, PR reviewer, and project community.

For a long time, I focused on the responsibility of the reviewer to make the PR author comfortable (for example, compliments, gifs). Don’t get me wrong – I think one of the most important parts of a senior developer’s job is to provide constructive, actionable feedback.

But I now understand that the PR author’s sense of agency and desire to learn are just as important.

A sense of agency is a sense of control over actions and consequences. In other words, the PR author needs to feel that they have control over what goes into their PR. Before npmx, I understood this a little bit. I always ask “why?” because I’m not putting my name on code that I don’t understand and agree with. I have counseled my own junior developer that it’s his job to get PRs he’s authored reviewed and merged.

After experiencing an in-depth code review outside of work, I finally understand that a PR is a process. Reviews exist to get consensus, so “perfect” is far more subjective than I originally thought. There’s a reason you get a conversation, not a grade.

Maybe I’ll even ignore some nitpicks in the future.

A desire to learn makes remaining open to a reviewer’s suggestions and requests a lot easier. During my first npmx PR, it was only when my desire to learn outweighed my desire to prove something that I started having fun.

Conclusion

Today, March 3rd, 2026, is the alpha release of npmx, and I am very proud to be a contributor and member of the community.

I look forward to learning about OSS from Patak, fancy, smart code from Daniel, outreach from Salma, and accessibility from Knowler. I know I’ll learn many things outside of that list, too. I’m grateful I’m not the smartest person in the room and that I finally get to have fun with Pull Requests.

In an ideal setting, you would write code for a feature, add that code to the staging area, and then commit it before going to the next part. This helps keep your commit history clean. (Don't worry if you don't have a clean history. Many of us don’t.)

But now, imagine a scenario where you have multiple features to build. You've committed the first. You've started the third, but then you found out you needed to build the second one first, because the third depends on it. It might seem like you have to go back in time and build out that second feature without mixing in the code changes for the third, and without deleting the code changes for the third.

So how do you do that?

In this article, you’re going to learn about Git stash, what it is, and the basic commands you need to be able to use it.

What We’ll Cover:

• What is Git Stash?

• How to Use Git Stash

  • Pushing Commands To The Stash

  • Applying Changes From The Stash To The Working Directory

  • Listing The Items In The Stash List

  • Removing Items From The Stash

  • Creating A New Branch From Stash

  • Showing The Changes In The Stash

• Conclusion

To understand and get the most out of this tutorial, you’ll need to have a basic understanding of Git.

What is Git Stash?

Git stash provides storage (in the form of a stack) where you can store changes to your code. It lets you keep these changes separate from the current working directory until you're ready to apply them.

git stash is a relatively simple command, and has a few variations like:

• git stash push

• git stash pop

• git stash apply

• git stash drop

• git stash clear

• git stash show

• git stash list

How to Use Git Stash

Pushing Code Changes to the Stash

To push uncommitted changes from the working directory to the stash, you can use git stash push. When you do that, the changes disappear from the working directory and are saved in the stash. The working directory is then set back to the last commit (which, in the example below, is the Feature one).

git stash push

You can also write the git stash push command as just git stash – it means the same thing and performs the same way. You can also add a message to it with the -m or --message flag:

git stash push -m "Feature two I was working on"

You can use the -u flag or --include-untracked to include untracked changes in the stash. This way, the changes not yet tracked by Git can be included in the stash.

git stash push -u
git stash push --include-untracked

On the other hand, you can decide to push only staged changes to the stash with the -s or --staged flag:

git stash push -s

You can also suppress feedback messages with the -q or --quiet flag:

git stash push -q

When you're done with your edits on the current working directory, you can commit and push without the older changes bleeding into it. They're safely stowed away in the stash.

Anytime you use the git stash command, you add a stash to the stash list. The stashes are identified by their index numbers.

Applying Changes from the Stash to the Working Directory

Let’s say you had a quick fix to do. You’re done committing that, and you want to continue with what you were working on. You can restore the changes from the stash to continue working on them.

You can do this by using the git stash apply command or the git stash pop command:

git stash apply

git stash apply applies the latest changes from the stash to the working directory, but doesn’t delete the code from the stash. You can select a particular entry to apply by index number:

git stash apply --index stash@{1}
# You'd need to use quotes "stash@{1}" if you're writing this in PowerShell

git stash pop, on the other hand, applies the latest changes from the stash, then deletes them from the stash. Basically, popping from a stack. You can select a particular stash entry to pop by index number.

git stash pop

git stash pop --index stash@{1}
# You'd need to use quotes "stash@{1}" if you're writing this in PowerShell

Listing the Items in the Stash List

You can use git stash list to list out the stashes in the stash list. It’s arranged by index number (like {0}, {1}, and so on). Any time you do a git stash push, it adds a stash to the stash list.

git stash list
stash@{0}: WIP on master: b2a2709 Feature one
stash@{1}: WIP on master: b2a2709 Feature one

Removing Items from the Stash

You can use git stash clear to clear the stash list. But if you just want to drop a particular entry from the stash list, you can use git stash drop and specify the entry you want to drop by the index number. This doesn’t apply its changes to the working directory.

git stash clear

git stash drop stash@{0}
# You'd need to use quotes "stash@{0}" if you're writing this in PowerShell

Creating a New Branch from Stash

You can also create a new branch from a stash using git stash branch. The syntax is git stash branch <branchname> [<stash>].

git stash branch premium-branch stash@{0}
# You'd need to use quotes "stash@{0}" if you're writing this in PowerShell

If you don’t add the stash index, it will just use the last stash.

git stash branch premium-branch

Showing the Changes in the Stash

You can use git stash show to show the changes you’ve made in your stashed changes.

C:\file-path\git_stash_example> git stash show
 text.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

Conclusion

Git stash is one of those quiet tools that becomes indispensable once your workflow starts to get messy. It allows you to shelve unfinished ideas, switch context without panic, and keep your commits clean. With it, you can safely carry out urgent fixes, and juggle dependent features without muddling up your commit history.

If you enjoyed this article, share it with others. You can also reach me on LinkedIn or X.

To start, let’s clear one thing up: Git and GitHub are not the same thing.

In short, Git is the tool that runs on your own computer and keeps track of changes in your files, while GitHub is an online platform that lets you store those Git projects in the cloud and collaborate with other people. Git works perfectly fine on its own, but GitHub makes teamwork, sharing, and backup much easier. They’re connected, yes, but completely different.

Think of it this way – Git is the “coffee,” and GitHub is the “coffee shop” where that coffee is served. Fun analogy, right? Don’t worry, in just a moment you’ll see exactly what that means.

What Does Git Do?

So, let’s start by understanding what Git actually is and how it works. Simply put, Git is a powerful tool that constantly keeps track of every change you make to your files - and I mean literally all the time. Day or night, 365 days a year, Git records what changed, when it changed, who changed it, and even where it happened.

Now, what kind of files are we talking about? Almost any kind – not just code. It could be an image, a text file, JavaScript, PHP, Python, or even a video. No matter what you’re working on, Git tracks every single change. Pretty amazing, isn’t it?

But here’s the best part: the magic of Git doesn’t stop there. The coolest thing about Git is that it saves different versions of your files. Imagine you wrote some code and then made a few changes to it after a few days. Now you want to make sure the old version doesn’t get lost. That’s exactly where Git comes to the rescue. It lets you keep multiple versions of the same file effortlessly, and whenever you want, you can roll back to any previous version in just a moment.

By the end of this handbook, you’ll not only understand what Git and GitHub are, but you’ll also be able to use them confidently in real projects. You’ll learn how Git tracks changes locally, how repositories work, how to move changes through Git’s workflow, and how to collaborate with others using GitHub.

We’ll start from the very basics and gradually move toward more advanced concepts like branching, merging, resolving conflicts, and safely undoing mistakes – all with hands-on examples you can follow along with.

Here’s What We’ll Cover:

1. Prerequisites

2. What is Git?

   • Git vs GitHub

3. Git Architecture – Local and Remote

4. How to Install Git on Your Computer

5. How to Create a Project and Initialize a Local Repository

6. How to Create a Remote Repository on GitHub and Clone It

7. How to Track Changes with git status

8. How to Move Changes to the Staging Area with git add

9. How to Save Work Permanently with git commit (and Configure Git)

10. How to Delete and Restore Files with git rm and git reset

11. How to View Commit History with git log

12. Branching and Merging in Git

    • Understanding Merge Conflicts

13. How to Navigate History with git checkout and Compare Commits with git diff

14. How to Work with Remotes: git push, git fetch, and git pull

    • Example – git push

    • Example – Pushing Other Branches

    • Example – git fetch

    • Example – git pull

15. How to Undo Local Changes with git restore

16. How to Temporarily Shelve Work with git stash

17. How to Undo Commits Safely with git revert

18. How to Keep History Clean with git rebase

19. How to Collaborate on GitHub with Pull Requests

20. Git & GitHub – Concise Summary

    • Git vs GitHub

    • Core Git Architecture & Workflow

    • Getting Started

    • Seeing & Moving Changes

    • Deleting, Restoring & Undoing

    • Branching, Merging & Conflicts

    • Navigating & Comparing History

    • Working with Remotes (GitHub)

    • Temporarily Shelving Work with git stash

    • Keeping History Clean with git rebase

    • Collaboration with Pull Requests (PRs)

    • Big Picture Takeaways

21. Final Words

Prerequisites

• Basic File & Folder Navigation – Using Finder / File Explorer.

• CLI Usage – Running simple commands in Terminal or Command Prompt.

• Text Editor – Any editor for opening and editing files.

I’ve also created a video to go along with this article. If you’re the type who likes to learn from video as well as text, you can check it out below:

What is Git?

Git is most commonly used in coding projects, but its power goes far beyond just code. You can use Git to keep track of changes and maintain different versions of almost any file. This means you never have to worry about losing a file or accidentally overwriting something important.

Let’s look at a real-life example. Suppose you’re working on a project. You’ve spent hours writing code, your client loves it, and everything’s going great. Then, a month later, the client asks for some new changes. You make the updates as requested. But after a few days, the client comes back and says, “Actually, the old version was better.” Now you’re in trouble, right? Because you’ve already overwritten the original code. How do you get it back?

That’s exactly the kind of problem Git solves. This is why Git is known as a Version Control System – it keeps every version of your files or code safely stored, so you can go back to any previous state whenever you need to, without losing a thing.

Git was created by Linus Torvalds – the same brilliant mind behind Linux. And honestly, what he built is nothing short of genius. Most tools programmers use have a short lifespan, but Git is one of those rare ones that, once you learn it, stays useful for the rest of your career.

The best part? The basics of Git aren’t that hard to learn at all. It’s built around a few simple commands and concepts, and once you understand those, the whole system starts to make perfect sense.

Still, for beginners, Git can feel a little confusing at first – and that’s exactly why this handbook exists. Think of it not just as a tutorial, but as a complete learning resource for learning Git inside and out. We’ll cover all the essential topics you’ll actually use in real-world projects. And if you want to jump to a specific topic, you can easily find it by using the section headings in the table of contents after the intro.

If you follow this tutorial closely, you’ll be able to understand every part of Git, step by step.

Git vs GitHub

Now, let’s move on to another important topic: the difference between Git and GitHub. Git is a tool that runs locally on your own computer. It tracks all the changes you make to your files and keeps everything organized.

But imagine this: you and your teammate are working on the same project. You’re coding on your own computer, and your teammate is working from another one. That means you both have different versions of the same project, right? And if your team has more members, there will be even more versions – each saved separately on their own machines.

This is exactly where GitHub comes in. When the project is complete, you’ll need to combine everyone’s work into one place to merge all those changes together. For that, you need a central hub where everyone can upload their updates. You push your work there, your teammate pushes theirs, and GitHub brings it all together.

GitHub acts as that central online server where your team’s entire project lives, making it easy for everyone to see, edit, and share updates in one place, without any confusion.

But GitHub isn’t the only place where you can host your Git repositories. There are other popular platforms too, like GitLab and Bitbucket. These are also widely used and trusted by developers around the world. Still, among all of them, GitHub remains the most popular and widely adopted platform.

That’s why in this tutorial, our focus will mainly be on GitHub. It’s now owned by Microsoft and is maintained with great care and attention. Especially in the programming community and in the world of open-source projects, GitHub’s contribution is truly remarkable.

So without wasting any more time, let’s dive in and explore how Git and GitHub actually work – and see some real-world use cases that will help you understand their power in action.

Git Architecture – Local and Remote

Before you start working with Git, the most important thing is to understand its core concept: how it actually works and what its internal structure, or architecture, looks like.

Git is mainly divided into two major parts, Local and Remote.

• The Local part refers to your own computer, where you do all your work. This is where your files, code, and every change you make are stored.

• The Remote part, on the other hand, lives in the cloud. It’s where you push or upload your local work. In most cases, when you say “remote,” you’re usually referring to GitHub.

Now, let’s start with how the local part works. On your computer, the folder where you’re working on your project is called the Working Directory. This is where all the action happens: you write code, create new files, modify existing ones, and make changes as needed. And when you feel like, “Alright, this version looks good, I want to save this change,” that’s when you move on to the next stage in Git’s workflow.

So, what do you do next? You move your work to the “stage.” At first, this word might sound a bit unfamiliar, but once you use it a few times, it’ll make perfect sense. In simple terms, when you finish your work in the working directory, staging means you’re saying, “Alright, my changes are ready – they can move to the next step.” This staging process is the second phase in Git’s workflow.

Then comes the third phase where you take the staged files and send them to the local repository. You can think of the staging area as a middle ground – a temporary space where files sit between your working directory and the final save in the repository.

Once you’ve reviewed everything and you’re confident the work is correct, you “commit” it. Committing means permanently saving those changes to your local repository – that is, locking them in as a recorded version of your project’s history.

Now you might be wondering, what exactly is a repository? Simply put, a repository is a place where all the versions of your files and their complete change history are stored. In the case of a local repository, it’s a specific folder on your own computer. For a remote repository, it lives on a cloud server, like GitHub.

You can think of a repository as a digital cabinet for your code. It’s a secure place where Git neatly stores every record of your work and every change you’ve ever made. Inside this repository, Git automatically creates a few system files that track everything – your changes, history, commits, and more. These files are managed entirely by Git itself, and the whole system runs based on the data stored within them.

So if we summarize everything so far, it goes like this:

1. You work inside your local working directory.

2. Once you’re done, you stage your changes.

3. Then you commit those staged files to the local repository.

Up to this point, everything happens only on your own computer – nothing has been sent to the cloud yet. You need the cloud only when you want to share your code with others, access it from another computer, or keep it safely backed up.

That’s when you “push” your local repository to the remote repository. In other words, you upload it to GitHub. Think about it like this: just as you use Google Drive or OneDrive to store files, photos, or documents, you could technically keep everything only on your own device. But you store them in the cloud so that you can access them from anywhere, and even if something gets deleted locally, it stays safe online.

GitHub works the same way. It’s your cloud backup for code. So you see, the main purpose of this whole process is to make collaboration and remote access possible. Having a remote means you can easily send your code from the local repository to a cloud server, and if needed, pull that same code back to any other machine.

That’s the core idea of Git, and the foundation of the entire system rests on this simple concept. Beyond that, there’s nothing overly complex. Once you clearly understand this basic workflow, everything else in Git will feel much easier to grasp.

How to Install Git on Your Computer

Now, let’s see how to get started using Git from scratch.

The very first step before working with Git is installing it on your computer. It might already be installed on your machine, so just check first.

If you do need to install Git, you can download it directly from the official website. There, you’ll find different versions for the three major operating systems – Windows, macOS, and Linux. Simply choose the one that matches your system, and you’ll get clear download instructions right there.

If you’re on Windows, click on the Windows option, and you’ll see two download choices: one for 32-bit and another for 64-bit systems. Just pick the one that matches your setup, download it, and run the installer.

For Mac users, when you select the macOS option, you’ll also find instructions on how to install Git using Homebrew. Just follow those steps, and your installation will be done in no time.

And for those using Linux or other Unix-based systems, you can follow the installation guide provided on the site according to your distribution. The entire process is simple and straightforward.

Once you have Git installed, the next step is to open your terminal or command prompt. If you’re using a Mac, open the Terminal app. For Windows users, you can use either Command Prompt or PowerShell – both will work just fine.

But after installing Git, you’ll usually get a separate terminal called Git Bash. You can use that too if you prefer. Many developers like working in Git Bash because it feels very similar to a Linux terminal and makes running Git commands easy and intuitive.

On Windows, you can open Git Bash by right-clicking anywhere inside a folder and selecting “Git Bash Here”.

You can also open it by searching for Git Bash from the Start menu.

When it opens, you’ll see a terminal window that looks very similar to a Linux or macOS terminal, with a dark background and a command prompt ready to accept Git commands.

For the rest of this tutorial, I’ll be using macOS with the default Terminal app, but the Git commands themselves are exactly the same on Windows (Git Bash) and Linux. If you’re using Windows or Linux, you can follow along using your terminal of choice – only the way you open the terminal may differ slightly.

So now open your terminal. The first thing you need to do is make sure Git is properly installed, right? To check that, type a simple command in the terminal:

git --version

Then press Enter. As soon as you do that, you’ll see an output on the terminal showing the version of Git installed on your machine. Keep in mind that the version number might not be the same for everyone – it depends on when you installed Git and which update you’re using.

If Git is installed correctly, you’ll see this version output. But if it isn’t installed, you’ll get an error message instead. Hopefully, Git is now properly set up on your machine, and you’re ready to start using it.

How to Create a Project and Initialize a Local Repository

Now it’s time to get hands-on and do some practical work. As I mentioned earlier, Git can be implemented in any file or folder, right? So first, you need to create a few files and folders to work with.

Start by navigating to the desktop using the terminal:

cd ~/Desktop

Here, cd is a terminal command that stands for “change directory.” It simply means you’re moving from one folder to another. Hopefully, you’re already familiar with some basic terminal commands like cd, pwd, touch, and mkdir. If not, you can easily learn them using Google or tools like ChatGPT. They’re simple to understand.

Just remember, for Windows users, some of these commands might be slightly different. And keep in mind, commands like cd, pwd, touch, and mkdir are general terminal commands – not Git commands.

Now that you’re inside the Desktop directory, create a new folder where you’ll keep all your project files. Name it git-one:

mkdir git-one

Press Enter. You’ve now created a new folder named git-one inside the Desktop directory. Move into that folder like this:

cd git-one

You’re now inside the git-one folder, and this is where your Git project begins. Inside the git-one folder, create two files:

touch one.txt
touch two.txt

Next, create another folder named myfolder:

mkdir myfolder

Then use cd myfolder to enter the folder. Inside this folder, create another file:

touch three.txt

Now check everything you’ve created in your file system. On macOS, for example, you can open the git-one folder in Finder by running:

open .

Here, the dot means “the current folder.” As soon as you press Enter, Finder opens up. Inside the git-one folder, you’ll see two files, one.txt and two.txt, and a folder named myfolder, which contains the three.txt file.

Now write something inside each of the files. Open one.txt in a text editor, write one, and save it. Then open two.txt, write two, and save that as well. Finally, go inside the myfolder directory, open three.txt, write three, and save it. Now all three files contain some content.

This git-one folder is your working directory. As mentioned earlier, this is the folder where you’re doing all your work, and where all your files are stored.

If you want Git to start monitoring everything inside this git-one folder, you have to tell Git, “This is my project folder. Track all the changes here.” To do this, go back to the terminal, make sure you’re inside the git-one folder, and type this:

git init

The word init means “initialize.” In other words, you’re telling Git to start working inside this folder from now on. Once you run the command, it shows a message: “Initialized empty Git repository.” That means Git has now started tracking this folder.

So how do you know that? Since you’re inside the git-one folder, type this:

ls

You’ll see all the files and folders inside it. Now type:

ls -la

Notice that now you can also see a hidden directory named .git. The ls -la command lets you view hidden files and folders.

Operating systems hide certain files and folders by default to protect users from accidentally modifying or deleting critical system data. These hidden files usually store configuration, metadata, or internal information that regular users don’t need to touch. For example, you might see hidden files like .env, .DS_Store, or .config in different projects.

You can see a hidden folder named .git inside your project directory. Who created it? Git did. This .git folder is actually the core of the entire project. It’s where Git keeps all its internal data, such as which files have changed, who made the changes, and what the previous versions were. In short, everything Git does is stored right here.

The .git folder is hidden for the same reason: it contains Git’s internal database and configuration. You normally never edit anything inside .git manually. If this folder is deleted or corrupted, Git loses the entire history of the project. Hiding it helps prevent accidental damage.

From now on, Git will be able to track every change you make in your work. Let’s say you make some changes to the three files you created earlier. That means you now have a local Git repository. By running git init, Git created the hidden .git folder and started tracking this directory as a repository. From this point on, any changes you make to files inside this folder can be staged, committed, and recorded in Git’s history. Even though you haven’t made a commit yet, the repository already exists locally and is ready to track your work.

How to Create a Remote Repository on GitHub and Clone It

You can also create a remote repository directly. I mentioned this earlier, so let’s see how to do it. Open your browser again and go to:

https://github.com

If you’re new, you’ll need to create an account on GitHub first. If you’re already logged in, you’ll see your profile. On the left side, you can see your repositories, feeds, and other details. Your goal is to store your local files on GitHub.

To do that, you need to create a new repository on GitHub. Click the blue New button. Just like you used git init to create a local repository, here you can initialize one in the cloud. Give it a name – for example, git-journey – and in the description, write something like “You are learning Git and GitHub.” Keep it public so everyone can view it. Then click the Create Repository button. You’ve now created a new repository on GitHub.

Right now, the repository is completely empty – it doesn’t have any files in it. To add some files, click the Create a new file button, name it one.txt, and inside the file, write one. Then click the Commit changes button. The term “commit” basically means “save.” Committing is like saving a file – nothing complicated. Don’t worry about this too much now, as I’ll explain commits in more detail later.

For now, there’s already a default commit message saying “Create one.txt,” so you can keep that as it is and click Commit changes. Next, create another file the same way – this time naming it two.txt, writing two inside, and saving it. Now, if you check your GitHub repository, you can see two files there: one.txt and two.txt.

At this point, you have two repositories – one on the cloud (GitHub), and another one locally on your computer. You initialized the local one yourself earlier, but now you want to bring the GitHub repository down to your machine by cloning it.

Go back to your terminal. Suppose you’re currently inside the git-one folder, but you want to clone the remote repository onto your Desktop. In the terminal, type:

cd ../

This command takes you back to the Desktop. Now, you’re going to clone the remote repository – the one you just created on GitHub. For that, you need a link, which is the repository’s URL. Go back to GitHub, open that repository, and click on the Code button. There, you’ll see an HTTPS link. Copy that link. Then, in the terminal, type the following:

git clone <repository-https-link>

Replace <repository-https-link> with the link you just copied, and press Enter. Git pulls your GitHub repository down onto your local machine.

After a few moments, the cloning process is complete. To verify whether the repository has been successfully cloned, type in the terminal:

ls

Remember that this command shows the list of folders in your current location. You’ll see a new folder named git-journey, alongside your previous git-one folder. Enter the git-journey folder like this:

cd git-journey

You’re now inside the git-journey directory. If you type this:

ls

you can see the contents of the folder. Inside it you should see the two files, one.txt and two.txt. To see hidden files, type:

ls -a

You’ll find a .git folder here as well. That proves this is also a complete Git repository, cloned from the cloud. Earlier, you saw the same thing in your local repository, right? So, this is how you can create a Git repository in two ways – one by initializing it locally, and the other by cloning it from GitHub or any other remote server. No matter which way you create it, to start working with Git, initialization is always required.

How to Track Changes with git status

Now let’s look at something new. Suppose you’re currently inside the git-journey folder. This is the repository you just cloned from the remote, right? If you make any changes to this repository – for example, you open the file one.txt in a text editor, keep everything as it was, but add the number 1 at the end and save the file – you might want to know what exactly changed, or whether Git has detected the modification.

To check that, type in the terminal:

git status

As soon as you run this command, Git immediately tells you: modified - one.txt. This means Git has already detected the change you made in that file.

Now let’s say you make a small change in two.txt as well – just adding a 2 at the end – and then run git status again. This time it shows modified - two.txt. That means both files have been changed, and Git has detected both modifications.

This is exactly how Git continuously keeps an eye on every change you make. It’s like it’s always watching over your project. At any moment, you can run the git status command to see which files have been modified or updated.

In a real project, you’ll often work with multiple files at the same time, right? In that case, git status gives you a clear summary of the overall situation: what has changed, which files are new, and which ones are modified.

So, up to this point, you’ve learned that you can initialize Git in two ways – either locally or from a remote repository. And with git status, you can easily check what changes have been made in your working directory.

Now let’s move out of the working directory into the staging area.

How to Move Changes to the Staging Area with git add

So far, you’ve only worked inside the working directory. That means you’ve created and modified files, but you haven’t yet told Git to keep those changes. Now you’re going to move them into the staging area.

In Git’s terminology, the process of moving changes from the working directory to the staging area is called adding. Simply put, git add means telling Git, “I want to keep this change.” Right now, inside the git-journey folder, you have two files, and both have been modified.

Now create another folder inside git-journey, named myFolder:

mkdir myFolder

Use cd myFolder to enter that folder. Inside myFolder, create a new file named three.txt:

touch three.txt

Open three.txt in your text editor, write three, and save the file. Now, you’ve made quite a few changes:

• You created a new folder.

• You added a new file.

• You modified some existing ones.

Your entire project has gone through multiple changes. Go back to the repository’s root folder (the git-journey folder) by running this:

cd ..

From here, check which files have actually been changed:

git status

Git shows that two text files have been modified, and a new folder has been created. Git also says that the old files are “tracked,” while the new folder is “untracked.” Why is that? Because the old files came from the remote repository you cloned earlier, so Git already knows about them. But since myFolder is newly created, Git doesn’t recognize it yet.

If you want to move everything to the staging area at once, you have two options: use git add --all or the shorter version git add -A. Both commands do exactly the same thing. Try it out:

git add --all
git status

Git has staged everything. All the changes you made are now “ready to commit.” You’ll learn more about commits in detail later. For now, just remember that when you use git add --all, Git takes every change and prepares it for the next commit. If you want to go back to the previous state – that is, remove everything from the staging area and return them to the working directory – type this:

git reset
git status

You’ll notice everything is back to the earlier state.

Now try git add -A:

git add -A
git status

You’ll see that Git has staged everything again. So whether you use git add --all or git add -A, both do the same thing – Git stages every change. Next, run:

git reset
git status

Everything is unstaged again. Now, in this state, if you type this:

git add .

at first glance it seems like it’s doing the same thing as git add --all, as everything appears to be staged. But there’s an important difference. Reset again:

git reset

Now go inside the myFolder directory:

cd myFolder
git add .
git status

Git has only staged the three.txt file that’s inside myFolder. The other files in the root folder are still unstaged. This difference is really important:

• git add --all or git add -A stage every change across the entire project.

• git add . stages only the changes within the current directory (and its subdirectories).

Also, if there were a subfolder inside myFolder, using the dot would still include the files inside that subfolder too. In simple terms, the dot means “the current directory and everything inside it.”

So now you’ve seen three variations of the git add command: --all, -A, and . (dot). The first two work exactly the same way, while the dot version is limited to the current directory. Now run:

git reset
git status

to bring everything back again. Return to the root folder:

cd ..

And stage everything again:

git add --all

Now all files are ready to commit. At this point, imagine you make some changes directly in the working directory. For example, you delete the file two.txt and create a new one named four.txt, writing four inside it. That means you’ve deleted one file and added another new one.

Check the status:

git status

Git shows that under “Changes to be committed,” the previously staged files are still there. But under “Changes not staged for commit,” it now lists two.txt as deleted and four.txt as untracked. Now type:

git add *
git status

Git has staged the newly created four.txt file, but it hasn’t staged the deleted two.txt file. That’s why it’s important to understand that git add * only stages new or modified files, but not deleted ones. So to summarize:

• git add * stages visible new/modified files, but not deletions.

• git add . stages changes in the current directory, including modifications and deletions.

• git add -A / git add --all stage all changes (additions, modifications, deletions) across the entire repo.

Reset again:

git reset
git status

If you want to stage only a specific file – say one.txt, which has been modified – you can do that by typing:

git add one.txt

Similarly, if you want to stage a file inside a folder (for example the file inside myFolder) you can write:

git add myFolder/three.txt

You can also stage a single file like this:

git add two.txt
git status

You’ll see that only two.txt has been staged. You can also stage files by their extension. For example, to stage all .txt files:

git reset
git add *.txt
git status

This command stages all .txt files in the current directory, excluding deleted ones and excluding files inside subfolders.

Finally, if you want to stage everything at once, a simple and common practice is to go to the root directory and type:

git add .
git status

All the changes are now staged together. That means all your changes have been moved from the working directory to the staging area.

How to Save Work Permanently with git commit (and Configure Git)

So far, you’ve learned how to move changes from the working directory to the staging area using the git add command. Now let’s see how to save those changes from the staging area to the local repository. In Git’s language, this is called a commit. It means you’re confirming and saving your changes permanently.

You can think of it like getting ready for a party. You don’t just walk straight out the door. First, you stand in front of a mirror and check your clothes, shoes, accessories, and hair. That’s the stage where you make adjustments – maybe you realize, “This shirt doesn’t look good,” or “Let me change these shoes.” That’s an intermediate step. You haven’t left for the party yet – you’re just making sure everything is in order. If something’s off, you can fix it right there. Once you’re satisfied and everything looks perfect, that’s when you finally leave for the party.

Git works in the same way. Instead of going straight from the working directory to the local repository, you first move your changes to the staging area. This is an intermediate step where you can review, adjust, or even remove changes before saving them permanently. You don’t commit directly from the working directory because the staging area gives you a chance to verify everything before finalizing. When you finally “commit,” it means you’re sure everything is correct – no more mistakes – and now the work can be saved permanently. That’s why this process is called a commit.

First, check your current state:

git status

It shows that the staging area contains some changes that are ready but not yet committed. To commit them, write this:

git commit -m "I have made some changes to files"

The -m flag lets you add a short message describing what you changed.

Sometimes an error may appear the first time you try to commit. When you install Git for the first time and attempt a commit, you might see a message like this:

*** Please tell me who you are

This is completely normal. It’s just Git’s way of asking for your identity before recording a commit. Git needs to know who is making the changes and from which email address. This information is attached to every commit in the project history, which later helps track who made which changes.

Fixing this issue is simple. Git tells you exactly what to do. Run the following two commands:

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

By running these two commands, the problem is solved. The first command sets your email address, and the second sets your name. The --global flag means that this configuration will apply to your entire computer - so every Git commit you make from this machine will use the same name and email.

If you want to make the configuration specific to a single project, you can use the --local flag instead. That way, the settings will apply only to that particular repository.

In short, when you use Git for the first time, setting up your user configuration is mandatory. It’s part of the basic Git setup you need to do before committing. Once it’s configured, Git will automatically recognize your identity for all future commits. If Git is already configured, you don’t need to set it up again.

Now, let’s go back to the main task of making a commit:

git commit -m "I have made some changes to files"

Now the commit is done. The terminal shows how many files were changed, how many lines were added, and how many were deleted. You can verify everything by checking the status:

git status

Everything looks clean now, meaning all the changes have been successfully saved in the local repository. From now on, whenever you make new changes to any file, you’ll have to stage and commit them again, just like before.

One more thing about commits: you can always roll back to the previous state if needed. To do that, type the following:

git reset HEAD~
git status

This command will undo the last commit and bring everything back to the working directory. You’ll see that all the files have returned to the working directory, ready to be staged again. You can now modify or commit them as you wish.

This shows how much control Git gives you over your work. It’s just about remembering the right commands.

Before we move on to deleting and restoring files, go ahead and make a new commit again so you’re working from a clean state:

git add .
git commit -m "I have made some changes to files"

How to Delete and Restore Files with git rm and git reset

Now the commit is done. Manually delete the one.txt file from your file system and then go back to the terminal. Type:

git status

Git shows that one.txt has been deleted. If you then type:

git add .

the deletion will also be staged. Instead of deleting a file manually and then adding it again, you can perform both steps in a single command. If you want to delete a file and stage that deletion at the same time, type:

git rm four.txt

Here, four.txt is just an example. This command deletes four.txt and automatically moves that change to the staging area. Once you run this and check the status:

git status

you’ll notice that four.txt has been deleted and staged. You no longer have to perform two separate steps – deleting and adding manually. You can do both at once with this shortcut.

If you check in your file explorer, you’ll see that four.txt has disappeared. Now, roll back the deleted file using git reset. When you run a regular git reset, it only brings back the staged changes, not the deleted files. You’ll see the message “Unstaged changes after reset.” But if you check your file system, the deleted file hasn’t returned. That’s because a regular reset only brings back staging information, not the physical file. You can confirm this with:

git status

You’ll notice only the changes are back, and that manually deleted files are still missing. If you want to restore everything (both the changes and the deleted files) you have to run:

git reset --hard

Once you execute this, both your changes and the deleted files return to their previous state.

Now let’s explore the use of git rm a bit deeper. Suppose you want to remove a file. First, reset everything:

git reset --hard

Now you’re back to your original state. Edit the four.txt file and write 4 inside it. That means there’s now a modification in the working directory. If you try to delete it directly using:

git rm four.txt

the file isn’t deleted, and Git shows an error: “the following file has local modifications.” This means Git isn’t allowing the deletion because it has detected uncommitted changes in that file.

Before you can remove it, you either have to commit those changes or confirm that you truly want to discard them. If you’re sure you want to delete the file anyway, you can force it by using:

git rm -f four.txt

As soon as you run this command, the file is forcefully deleted. If you check your file explorer, you’ll see that four.txt is gone. Now consider another situation. Run another hard reset:

git reset --hard

This brings everything back again. Modify four.txt by writing hello inside it. Now, if you type:

git rm --cached four.txt

this removes the file from the staging area but keeps it physically in your working directory. Check it:

git status

You’ll see that four.txt has moved to the “Untracked files” section: it’s no longer staged, but the file itself still exists in the system. That’s the difference between the --force and --cached flags:

• git rm -f completely deletes the file.

• git rm --cached removes the file from staging (and from tracking), but keeps it in your working directory.

Another useful command is:

git rm -r folder

Here, the -r flag stands for “recursive.” This means if the folder contains other subfolders or files, all of them will be removed recursively. If you mention the folder name without -r, then only that folder will be removed, not its contents. Try this out. Reset everything again:

git reset --hard

Now experiment with myFolder:

git rm -r myFolder
git status

The folder is deleted from your file system as well, and myFolder is listed as deleted and staged automatically. Reset everything again:

git reset --hard

How to View Commit History with git log

So far, you’ve made quite a few commits. Now you’ll learn how to view those commits. Viewing commits means checking the commit log. In the terminal, type:

git log

You’ll see the full commit history. You might see three commits, for example. Along with each one, there are details and messages that clearly describe what was done in that commit.

You’ll also notice long random strings which are commit IDs. Using these IDs, you can go back to previous versions later on. The first two commits might be the ones created when you made files while setting up your GitHub repository, and the last one might be when you modified some files recently.

If you want to view this log in a cleaner, more compact format, you can use:

git log --oneline

Once you run it, you’ll see a short summary of each commit with just the essential information. The commit IDs are also shown in a shortened format. These shortened IDs can also be used to return to any previous version later on.

Branching and Merging in Git

Now let’s move on to one of Git’s most powerful and important features: branching. At the moment, your repository has only one branch. A branch in Git is like a separate line of development where you can work independently.

If you check the online repository you cloned earlier, you’ll see that the default branch is called main. This is the default branch where all work begins. In recent times, Git has shifted from calling it “master” to “main,” but the idea remains the same: the main branch is your project’s central line of development.

To understand branching more simply, imagine you’re working in the kitchen of a large restaurant. The main branch is the main kitchen where all the dishes are prepared and served to customers. Now, if your client wants to try a new dish or recipe, you wouldn’t experiment directly in that main kitchen, because if something goes wrong, it could ruin everything.

Instead, you create a separate test kitchen where you can safely prepare and test the new dish. Once the recipe is perfected, you bring it back into the main kitchen to serve it officially.

Git works exactly the same way. Instead of making changes directly in the main branch, you create a separate development branch where you test and commit all your changes. Once everything is stable and verified, you merge that branch back into the main branch. This ensures that your main project stays safe, while new features can be developed and tested without breaking anything.

In short, branching in Git provides a secure and organized intermediate step that allows you to review, test, and manage changes before merging them into the main codebase.

Since I’ve already mentioned the word “merge”, let’s understand what it means. Merging simply means combining the changes from two branches into one. It’s an important concept for understanding how branches work.

In Git, you can create multiple branches – like staging, development, frontend, or backend – and work on each of them separately. Once all the changes are finalized and tested, they’re merged back into the main branch.

Right now, your application has only one branch. To see how many branches you have, type:

git branch

This command shows the list of all branches. At the moment, you may have only one, and the branch you’re currently in has a star (*) next to it.

To create a new branch, type git branch followed by the branch name. For example:

git branch development
git branch

You’ll see two branches listed: main and development. The star next to main means you’re still on the main branch. You can easily switch from one branch to another.

When a new branch is created, it takes the exact state of the branch you were on at that moment. So, in this case, the development branch is an exact copy of the main branch. Whenever you create a new branch, it inherits the current state of the branch you’re in.

Now that you’ve created a new branch, switch to it:

git checkout development
git status

You’re now inside the development branch. If you check the status, everything looks clean, because the development branch was created with the same content as main. Go to your file system and create a new file named three.txt. Inside it, write three. Then, back in the terminal:

git status
git add .
git commit -m "I created three.txt and entered three there"

Now your commit is done inside the development branch. Next, switch back to the main branch:

git checkout main

When you check your file system now, you’ll notice that three.txt is no longer there. Why? Because the changes made in the development branch exist only in that branch. Those changes haven’t been merged into main yet. The moment you switch back to main, Git automatically hides the changes made in development, showing you only what exists in the main branch.

This demonstrates how much control Git has over your file system. When you switch branches, Git instantly adjusts which files are visible so that you only see the changes relevant to that specific branch. There’s no duplication or conflict in your file system, as Git manages everything seamlessly.

In this way, you can create hundreds of branches, each containing its own set of changes, and Git will always show you a separate, isolated view for each one.

For any change to take effect, you must commit it. Whatever branch you’re working in, the commit must be made there. Once committed, Git understands that those changes belong exclusively to that specific branch. That’s why, when you switch back to the main branch, the changes made in the development branch don’t appear there.

Now suppose you make a new change to the four.txt file while you’re on the main branch – you add a 4 to it. Then, if you check the status:

git status
git add .
git commit -m "I changed four.txt and added additional 4"

Now, both branches have changes – the main branch has this new commit, and the development branch still has its previous one. Since both branches now contain updates, you’ll need to merge the changes.

First, switch to the development branch:

git checkout development

Now run:

git merge main -m "merging main into development"

After the merge, the changes made in the main branch appear inside the development branch as well. For example, the updated four.txt file is now present in the development branch alongside the previous changes. Both branches’ updates have been combined, and the development branch now reflects all the latest modifications.

Next, switch back to the main branch:

git checkout main

The changes from the development branch haven’t yet appeared here. From main, merge everything from development:

git merge development -m "merging on main with development"

After running this command, you’ll see that the three.txt file from the development branch now appears in main as well. Both branches’ changes have been successfully merged, and the merge process is complete.

Understanding Merge Conflicts

Sometimes during a merge, conflicts may occur. A merge conflict happens when the same part of a file has been changed differently in two branches.

For example, if you modified one.txt in the main branch and someone else modified the exact same section of one.txt in the development branch, Git won’t know which version to keep.

In such cases, Git flags the file as having a conflict, and you have to resolve it manually by deciding which changes to keep – or by merging both versions yourself.

Right now, you’re on the main branch. From here, you’ll create a new branch so that main remains untouched while you simulate a conflict. Run:

git branch staging
git checkout staging

This creates a new branch named staging, which contains all the latest updates from main, and switches you to it. While working on the staging branch, go to four.txt. At the end of this file, there was the number 4. Add 44 at the end and save the file. Now the staging branch has a change.

Run the following:

git status
git add .
git commit -m "changed 44"

The staging branch work is done. Next, switch back to the development branch:

git checkout development

When you open four.txt here, you don’t see the 44 you added earlier in staging. So, write 444 and save the file. Then run:

git add .
git commit -m "added 444 on four.txt"

The development branch now has its own separate change. While staying in the development branch, try to merge the changes from the staging branch:

git merge staging

Git fails to merge automatically and shows an error:

Automatic merge failed; fix conflicts and then commit the result.

This happens because the same line in four.txt was modified in both branches, staging and development. Git can’t decide which version should take priority, so it leaves the decision to you.

In this case, the developer working on the development branch (or whoever is managing it) has to manually resolve the conflict. When you open four.txt in a text editor, Git marks the conflicting section clearly, showing which part came from staging and which part came from development. You’ll see both the 44 from staging and the 444 from development. It’s now up to you to decide whether to keep one, remove one, or combine both changes.

While staying on the development branch, you decide which version to keep – for example, 444. You’ll then need to remove all the conflict markers, save the file, and then run:

git add .
git commit -m "merge conflict solved"

Now switch back to the staging branch:

git checkout staging

When you open the file system and check four.txt, it still shows 44, meaning no change has been applied yet. At this point, you can choose to merge changes either into staging or development since both branches are now in sync in terms of expected final content.

From staging, run:

git merge development

This time, Git merges everything smoothly without any conflict because both sides now contain compatible content. When you check the status:

git status

it shows everything is clean. Now, if you want to bring these merged changes into the main branch, switch to it:

git checkout main

Once you’re on the main branch and open the file system, you may notice that four.txt doesn’t yet have the latest update. Merge the staging branch:

git merge staging

All the latest changes flow into the main branch. The updates from both branches now combine into the final version. That’s how the entire process of merging and resolving merge conflicts works. You’ve now seen how branching works and how to switch from one branch to another using git checkout. Let’s dig a bit deeper into that command.

How to Navigate History with git checkout and Compare Commits with git diff

Earlier, when we talked about git log, I mentioned that you can go back to a previous version using a commit ID. That’s what you’ll see now – and to do that, you’ll again use git checkout.

First, check your commit history:

git log --oneline

Suppose you have nine commits in your log. Make a small change. Open one.txt and write hello inside it. Then stage and commit:

git add .
git commit -m "update one.txt file"

Next, run:

git log --oneline

All the commits are displayed. Now let’s say you want to switch back to one of your previous commits, specifically the one named “merging main into development.” To do that, copy the commit ID of that commit and type:

git checkout <that-commit-id>

Earlier, when you switched branches, you used the branch name. This time, you’re using a commit ID instead. Remember, your commit ID will be different.

After running this command, the project moves from the main branch to the exact state it was in at that previous commit. You must ensure that all your changes on main are tracked and committed before doing this. If there are any untracked or uncommitted files, Git won’t allow you to checkout to a previous version.

Once you run the command, you’ll see that in the terminal, instead of showing main, it now says something like:

HEAD detached at <commit-id>

That means you’ve successfully switched to that particular commit. If you open one.txt now, you’ll notice that the hello line you added earlier is no longer there. This confirms that you’ve returned to the previous version of your project.

If you want to go back to your latest state – meaning returning to the main branch – use:

git checkout main

You’ve switched back to the main branch, and you’re back to the most recent version of your project.

So now you’ve seen how to switch between commits and move from one version to another. Now we’ll explore how to compare one commit with another.

If you want to see the differences between your current commit and a previous commit (that is, what lines of code were added, what lines were deleted), you can do that easily using Git commands.

First, check your commit history again:

git log --oneline

Suppose there are now 10 commits in total. You’ll compare the commit “update one.txt file” with the previous one “merging main into development.” For that, you’ll need the commit IDs of both.

Since you’ve already run git log, copy those two IDs. Once you have them, write the command:

git diff <first-commit-id> <second-commit-id>

After running this command, Git shows the exact changes made between those two commits. The terminal displays which files were changed, what was removed (usually in red), and what was added (usually in green).

One important detail: in git diff, when you place the most recent commit ID first and the older one second, Git shows differences from the perspective of the newer commit – that is, what’s newly added or removed compared to the older one. If you reverse the order (older commit ID first and newer second), Git shows the opposite perspective. Try running the command both ways a few times and you’ll easily understand how the comparison works.

If you’re ever inside an interactive log or diff view, you can exit by pressing q on your keyboard. That closes the view immediately.

How to Work with Remotes: git push, git fetch, and git pull

So far, everything you’ve done has been inside your local repository – staging files, making commits, and storing everything locally. But the real goal is to send those updates to the remote repository, like GitHub.

When you send local changes to a remote repository, that process is called a push. If any changes have been made in the remote repository that you want to bring into your local repository, you can use fetch.

When you run git fetch, the remote changes are downloaded into your local repository’s memory, but they won’t appear in your working directory yet. To update your working directory and see those changes in your files, you need to run git pull.

In short:

• push sends local changes to the remote.

• fetch brings remote changes into your local repository (but does not merge them into your working directory).

• pull fetches and merges; it updates your working directory immediately.

In other words:

git pull = git fetch + git merge

Example: git push

You’ve already made several changes in your local repository, and now you want to push them to the remote main branch. Since you’re currently on the main branch, use:

git push origin main

Here, origin refers to the remote repository, and main is the branch you want to push to. After running this command, all your latest commits are sent to the remote main branch. If you check your repository on GitHub, you’ll see that everything is updated. But only the main branch is pushed – other branches aren’t uploaded yet. This means you’ve only pushed your main branch to the remote’s main.

Example: Pushing Other Branches

Switch to the staging branch:

git checkout staging
git push origin staging

Git creates a new branch named staging in the remote repository and pushes all your staging changes there. When you check GitHub again, you’ll see that the staging branch has been created and updated.

Similarly, switch to the development branch:

git checkout development
git push origin development

The development branch is also uploaded to the remote. Now all three branches (main, staging, and development) are fully synced with the remote repository.

Finally, switch back to the main branch again:

git checkout main

Example: git fetch

Imagine you’ve already pushed your local changes to the remote. Now let’s see how git fetch works.

Suppose you make a change directly on GitHub. For example, open the file three.txt on GitHub, type 3, and commit the change. Now, the remote main branch has a new update that your local main branch doesn’t have – it’s behind the remote version. While staying on the local main branch, bring in the latest changes from the remote:

git fetch

Git fetches the new changes from the remote repository, but those updates don’t yet appear in your local file system. For example, you won’t see the update in three.txt until you merge the fetched changes. Once you run:

git merge

the remote changes are integrated into your local working directory as well.

Example: git pull

Now, suppose you edit the remote three.txt file again, this time adding 33 after 3 and committing it on GitHub. The remote main branch is now ahead again.

To bring in all those updates and merge them into your local main branch at once, use:

git pull

git pull automatically performs both fetch and merge in a single command, meaning all the new remote changes, including the latest updates in three.txt, immediately appear in your local files.

You’ve now learned how to:

• push changes from local to remote (git push),

• fetch changes from remote without merging (git fetch), and

• pull changes from remote while merging them automatically (git pull).

These three commands are among the most frequently used Git operations and are more than enough for most daily development work.

How to Undo Local Changes with git restore

Now imagine you’re working on a project. You start developing a new feature, write a lot of new code, and modify several existing files. After some point, you realize that the approach you took isn’t working at all. But by then, you’ve already made changes across 10 to 15 different files – some with new code, some heavily modified.

In this situation, you want to discard everything and go back to the previous state. Would you really open each of those 10 to 15 files manually, remove all the new lines, and try to restore the old code one by one? How accurate or even possible would that be? Probably not at all.

In this case, the simplest answer is that it’s actually not practical manually. And the more complicated answer is that there’s no guarantee that everything will return to its exact previous state. This is exactly where the magic of the git restore command comes in.

The git restore command helps you revert any file or directory back to its previous state, meaning the state of the last commit. It’s mainly used to undo local uncommitted changes, or to remove changes that were added to the staging area using git add. Let’s test it. Suppose in one.txt, you write:

new feature

This repository already had some committed history. Now you’re just trying to develop a new feature. After writing the new code, you realize that the change you made in one.txt (adding new feature) was a mistake. The previous version was fine.

Since this change isn’t ready to be committed, you want to undo it and go back to the last committed state. To do that, run:

git restore one.txt

As soon as you run this command, the file instantly reverts to its previous state – the exact version from the most recent commit.

If you want to restore an entire directory instead of a single file, type the directory name after git restore and it’ll bring everything in that folder back to the last committed version.

If you want to undo all changes across the entire repository, run:

git restore .

This restores every file to its last committed state. If you’ve already staged some changes using git add, you can still undo them using the --staged flag. For example:

git restore --staged fileName
# or
git restore --staged .

This removes the files from the staging area but keeps the working directory unchanged.

In summary, the git restore command helps you bring any file or directory back to its previous (last committed) state. It’s mainly used to undo local, uncommitted changes before they’re ever committed.

How to Temporarily Shelve Work with git stash

Now imagine this: you’re working on a new branch, developing a big feature. It’s a long process, and you’ve already finished about half of it. But the work isn’t yet in a state to be committed.

Suddenly, another developer messages you saying there’s a new update on a different branch and you need to check it and give feedback. How will you switch branches without losing your unfinished work? Will you throw away all your progress using the git restore command?

Of course not. There’s no reason to go through that kind of hassle when Git gives you a much smarter way to handle this: using the git stash command.

With git stash, you can temporarily set aside your unfinished work, switch to another branch to do something else, and later bring all your changes back with a single command.

Let’s see how it works. Suppose in one.txt, you write:

another feature

You’re currently on the main branch. Now you need to switch to the development branch to review a new feature. So you type:

git checkout development

But Git throws an error:

error: Your local changes to the following files would be overwritten by checkout:
    one.txt
Please commit your changes or stash them before you switch branches.
Aborting

This happens because Git doesn’t allow switching branches when there are uncommitted changes – it’s protecting your work. But since your feature isn’t ready to be committed, this is exactly when you use git stash. Run:

git stash

The moment you execute this command, your uncommitted changes disappear from your working directory – but they’re not lost. Git has safely stored them in a temporary area called the stash. This lets you switch branches freely without affecting your unfinished work. Now, switch to the development branch:

git checkout development

You’ve now successfully switched branches. You can review the new feature, make notes, and do whatever you need to. Once you’re done, switch back to your main branch again:

git checkout main

Now, when you look around, you’ll see that your unfinished feature – the one you were working on earlier – isn’t there. It’s still saved in the stash. To bring it back, “pop” it out of the stash:

git stash pop

As soon as you run this, all your stashed changes reappear in your working directory. The pop command restores the most recently stashed work and simultaneously removes it from the stash list. If you’ve stashed multiple times, Git keeps them all in order – newest on top, oldest at the bottom. When you pop, it brings back the most recent one first.

If you want to reapply the stashed changes without removing them from the stash list (so that you can reuse them later), use the apply command instead:

git stash apply

Your changes are restored, but they also remain safely stored in the stash for future use. You can stash again:

git stash
git stash apply

You’ll notice it behaves almost the same as before, and the changes come back just like when you used pop. You already know that Git can store multiple stashes, and you can view a list of all those stashed changes. To see that list, type:

git stash list

You’ll see a list of all your saved stashes. Each stash item is marked with an identifier like stash@{0}, stash@{1}, and so on. You can use these identifiers to apply or pop specific stashes:

git stash pop stash@{0}
# or
git stash apply stash@{0}

Both commands work. The only difference is how they handle the stash afterward. To understand the difference more clearly, suppose you check your stash list:

git stash list

and see just one stash. If you previously used git stash apply, that stash item is still there. To remove a stash manually, use git stash drop. The drop command removes a specific stash from the stash list. For example:

git stash drop
git stash list

Now the stash list is empty. Since you used git stash apply earlier, all the changes are still in your working directory. Confirm that with:

git status

The changes you applied are still there. Now stash those changes again:

git stash
git stash list

You’ll see one stash entry again.

Then run:

git stash pop
git stash list

The stashed changes are restored into your working directory, and the stash list is now empty. pop brings your changes back and removes them from the stash list – it’s like taking them out permanently. Stash something again:

git stash
git stash list

Now run:

git stash apply
git stash list

The command works. Your files are restored, just like before. But the stash is still in the list. So here’s the key difference:

• git stash pop restores your changes and removes them from the stash list.

• git stash apply restores your changes but keeps them in the stash list for future use.

How to Undo Commits Safely with git revert

Now let’s talk about git revert. The git revert command is used to undo the changes made in a previous commit – but instead of deleting that old commit, it creates a new one that reverses those changes. In other words, it cancels out the effects of a previous commit while keeping the project history completely clean and traceable.

That’s why it’s called “revert”: because it doesn’t delete any commit. Instead, it creates a new commit that brings the project back to its previous correct state. Simply put, git revert means fixing an old mistake without erasing it.

For example, imagine you accidentally added too much salt while cooking. Instead of throwing the whole dish away, you adjust the flavor by adding some extra ingredients to balance the saltiness. Similarly, git revert doesn’t delete the faulty commit – it corrects it through a new one.

To revert something, you need its commit ID. Suppose in the file three.txt, you added the line:

hello three

Then you run:

git add .
git commit -m "hello three"

Now, if you check the log:

git log --oneline

you’ll see there are 10 commits in total. You realize that the "hello three" commit introduced a bug and you want to remove it. Before that, copy the commit ID of "hello three" and then run:

git revert <that-commit-id>

After running the command, you’ll see a prompt asking for a commit message. You can type a custom message or simply keep the default one and exit (for example, by using - wq in Vim). Once you do that, the changes from "hello three" will be undone. Check the logs again:

git log --oneline

You’ll notice there’s a new commit added specifically for the revert. At this point, you might be reminded of git reset. The main difference between git reset and git revert is:

• git reset can take you back to a specific commit and discard all commits after that point, without creating any new commit.

• git revert removes the changes from a specific commit by creating a new commit that reverses it.

If your project is on GitHub or any remote repository, other contributors can also see the revert commit, ensuring clarity and preventing confusion.

Another key point is that if you check the logs after a reset, there’s no record of the removed commits. But when you use revert, you’ll clearly see an additional commit indicating that a revert took place.

How to Keep History Clean with git rebase

Now let’s talk about Git Rebase. Imagine you’re starting to work on a new feature. You create a new branch called feature by checking out from the main branch. You begin developing the new feature, making changes bit by bit, and committing your progress as you go. Meanwhile, another developer adds more updates to the main branch for production. Now you want to include those latest updates from main into your feature branch. What can you do?

There are several ways to handle this. As we’ve seen before, one option is to merge the main branch into your feature branch. If you do that, Git creates a new merge commit, and all the latest updates from main are merged into your feature branch.

But merging always creates an additional commit – you can see it clearly if you run git log. Some developers find these extra merge commits a bit messy. If you continue merging multiple times, your commit history can look cluttered.

In such cases, a better solution is to use Git Rebase. When you perform a rebase, the base of your feature branch changes. That means if you rebase onto main, all the new commits from main are applied directly into your feature branch, and then your feature branch commits are reapplied on top of them. While your main branch’s code content remains the same, the commit history becomes much cleaner and more linear – and you can easily verify this using git log.

Let’s understand this with an example. Create a new branch called feature from main:

git branch feature
git checkout feature

You’re now inside the feature branch. Open one.txt and add the line:

adding dark mode functionality

Then stage and commit:

git add .
git commit -m "adding dark mode functionality"

Now switch back to the main branch:

git checkout main

You’re now in the main branch. Create a new file called two.txt and write:

adding dark mode ui

Then stage and commit:

git add .
git commit -m "adding dark mode ui"

Now the main branch has a new feature – “dark mode ui”. You want that same “dark mode ui” update to appear in your feature branch as well. Switch back to your feature branch:

git checkout feature

Your goal is to bring the latest updates from the main branch into the feature branch. But this time, we’ll do it using rebase.

To perform a Git rebase, you need to be on the branch you want to rebase, and then specify the branch from which you want to bring the changes. For example, if you’re currently on the feature branch and want to bring in the changes from main, run:

git rebase main

Once you run this command, the rebase completes, and the “dark mode ui” update from the main branch appears in your feature branch.

Here’s what happens behind the scenes when you use rebase:

1. Git identifies the most recent common commit shared between your current branch (feature) and the branch you’re rebasing onto (main).

2. All the commits in your feature branch that come after that common commit are temporarily set aside.

3. Git applies all the new commits from the main branch into your feature branch.

4. Finally, it reapplies the saved commits from the feature branch on top of those main commits, one by one.

The result is a clean, linear commit history that’s much tidier than what you get with merging. You can easily see this difference by running git log.

Just keep in mind that git rebase is powerful. So it’s not recommended to use it on public repositories or branches where multiple developers are working together. If you must use it, you should always inform your team beforehand. Otherwise, it can cause serious issues.

The reason is that rebase rewrites existing commit history – even the commit hashes (IDs) change. So, if someone else is working on the same branch, your rebased commits won’t match their local copies anymore, and they won’t be able to pull or sync normally.

So before using rebase, make sure you fully understand where you’re applying it and whether it could cause problems for your collaborators. It’s perfectly safe to use rebase on your local or personal branches where only you’re working – just avoid rewriting commits that already exist on a shared remote branch.

How to Collaborate on GitHub with Pull Requests

Before wrapping up, let’s discuss one last important topic: the Pull Request. When working with Git and GitHub, the term “Pull Request,” often shortened as “PR,” comes up frequently.

A Pull Request is essentially a request you make to merge your changes into another branch – usually the main branch. It’s a way of saying, “I’ve made some changes in my branch. Please review them, and if everything looks good, merge them into the main branch.”

In other words, you typically don’t make changes directly to someone else’s repository. When you finish your work in your own branch, you create a Pull Request to ask for permission to merge your code into the main repository. That’s what a Pull Request is.

Go back to your git-journey repository on GitHub. By now, you’ve already pushed your main, staging, and development branches. At the top of the GitHub page, you’ll see several tabs: Code, Issues, Pull requests, and Actions.

Click on the Pull requests tab. Here, you’ll see a big green button labeled New pull request. This is where you can say, “I want to merge the changes from this branch into another branch.”

Once you click New pull request, GitHub shows you two dropdown menus:

• base: the branch where you want to merge the changes (select main here).

• compare: the branch from which you want to bring the changes (select development).

In other words, you’re saying, “I’ve made some updates in the development branch, and now I want those updates to be merged into the main branch.” GitHub automatically shows a detailed comparison: which files have been modified, which lines have been added, and which ones have been removed, with everything clearly visible. If everything looks good, scroll down and click Create pull request.

Give your PR a title, such as:

Merge development updates into main

In the description box, you can write something like:

This PR adds the latest updates and fixes from development to main.

Then click Create pull request to submit it. Now, if you go back to the Pull requests tab, you’ll see your newly created PR:

development → main

Click on it, and you’ll find three sections:

• Conversation: where you and your teammates can discuss or comment on the changes.

• Commits: which lists all the commits included in this PR.

• Files changed: which shows exactly what changes were made in which files.

If everything looks good after review, click the green Merge pull request button at the top, and then confirm by clicking Confirm merge. Once it’s done, GitHub displays a message:

Pull request successfully merged and closed.

That means all the updates from the development branch have now been successfully merged into main.

This is how Pull Requests make code management much easier. Every change gets reviewed first and then merged into main. As a result, the main branch stays stable, and the entire team can collaborate safely and efficiently.

Git & GitHub – Concise Summary

Git vs GitHub

• Git: Local version control tool that tracks every change to your files, lets you keep multiple versions, and roll back any time.

• GitHub: Online hosting platform for Git repositories that acts like a central “code server” so teams can share, review, and collaborate.

• Other Git hosts exist (GitLab, Bitbucket), but GitHub is the most widely used, especially for open source.

Core Git Architecture & Workflow

• Work happens in the working directory (your project folder).

• When changes are ready, you move them to the staging area with git add.

• You permanently record a version in the local repository with git commit.

• The remote repository (for example, on GitHub) is a copy of your repo stored in the cloud for backup and collaboration.

Basic flow:

1. Edit files in the working directory.

2. Stage changes: git add <files> or git add .

3. Commit: git commit -m "message"

4. Sync with remote: git push / git pull

Getting Started

• Install Git from the official site: https://git-scm.com/downloads.

• Check installation: git --version.

• Configure identity (needed before first commit):

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

  • git config --global user.email "you@example.com"

• Initialize a repo in a folder: git init.

• Or clone an existing repo from GitHub: git clone <repo-url>.

Seeing & Moving Changes

• Check what changed and what’s staged: git status.

• Stage changes:

  • git add --all / git add -A: stage everything (adds, changes, deletions).

  • git add .: stage changes only in the current directory.

  • git add <file> or git add *.txt: stage specific files or patterns.

• Unstage everything (but keep edits in files): git reset.

• Save staged changes as a commit: git commit -m "message".

• View commit history:

  • Full: git log

  • Compact: git log --oneline

Deleting, Restoring, & Undoing

• Delete a tracked file and stage the deletion: git rm <file>.

  • Force delete changed file: git rm -f <file>.

  • Stop tracking but keep file: git rm --cached <file>.

• Undo staged changes only: git reset.

• Reset everything (including working directory) to last commit: git reset --hard.

• Restore file content back to last commit:

  • Single file: git restore <file>

  • All files: git restore .

• Undo a commit safely (create a new “fix” commit):

  • git revert <commit-id>

• Move HEAD and history back to an earlier commit (dangerous on shared branches):

  • Example: git reset HEAD~ (undo last commit locally).

Branching, Merging, & Conflicts

• A branch is an independent line of development (for example, main, development, staging, feature).

• List branches: git branch.

• Create branch: git branch development.

• Switch branch: git checkout development (or git switch development in newer Git).

• Typical workflow: keep main stable, build new features on separate branches, then merge back.

• Merge another branch into the current one: git merge <branch-name>.

• If the same lines changed differently in two branches, you get a merge conflict:

  • Git marks conflicts in the file with <<<<<<<, =======, >>>>>>>.

  • You manually edit to the correct final content, then:

    • git add .

    • git commit -m "merge conflict resolved"

Navigating & Comparing History

• Jump to an old commit (read-only “detached HEAD” state): git checkout <commit-id>

• Return to the latest main: git checkout main.

• Compare two commits: git diff <old-id> <new-id> – shows what changed between them.

Working with Remotes (GitHub)

• Push local branch to remote: git push origin <branch>.

• Fetch latest state from remote without updating your working files: git fetch

  • Then merge if needed: git merge origin/main

• Pull and merge in one step: git pull (equivalent to fetch + merge).

Temporarily Shelving Work with git stash

• Use git stash when you have uncommitted work but need to switch branches.

• git stash: saves current changes and cleans your working directory.

• Switch branches, do other work, then come back and restore:

  • git stash pop: restore and remove from stash list.

  • git stash apply: restore but keep entry in the stash.

• See all stashes: git stash list.

• Remove a stash explicitly: git stash drop.

Keeping History Clean with git rebase

• git rebase <branch> replays your current branch’s commits on top of another branch, creating a cleaner, linear history.

• Safe on your own local branches, but dangerous on shared/public branches because it rewrites commit history (IDs change).

• Common pattern: on feature branch, run git rebase main to bring latest main changes under your feature commits.

Collaboration with Pull Requests (PRs)

• On GitHub, you usually:

  1. Push your feature branch.

  2. Open a Pull Request (PR) to request merging into main (or another base branch).

  3. Teammates review code, discuss in comments, and approve.

  4. The PR is merged (and usually closed) once accepted.

• PRs keep main stable and make reviews and history clearer.

Big Picture Takeaways

• Git tracks every change, lets you move safely between versions, and protects you from losing work.

• GitHub (or other remotes) adds backup, sharing, and collaboration.

• Most day‑to‑day work is based on a small set of commands: git status, git add, git commit, git push, git pull, git branch, git checkout, git merge, git log.

• Advanced commands like git reset, git restore, git revert, git stash, and git rebase give you powerful ways to undo mistakes and keep history clean.

Final Words

This tutorial on Git and GitHub has walked through the essential, day-to-day concepts in a step-by-step, practical way. It’s especially helpful for those who are just getting started. If you’ve always felt a bit intimidated or confused about using Git for the first time, this guide was created with you in mind.

If you found the information here valuable, feel free to share it with others who might benefit from it. I’d really appreciate your thoughts – mention me on X @sumit_analyzen or on Facebook @sumit.analyzen, watch my coding tutorials, or simply connect with me on LinkedIn. You can also checkout my official website sumitsaha.me for more details about me.

We just posted a course that will help you learn Git and GitHub from scratch with clear examples, real workflows, branching, merging, stashing, rebase, pull requests, and more. This course is great for beginners who want strong foundations. Sumit Saha developed this course.

Here are the things you will learn in this video:

• The difference between Git and GitHub in the simplest way

• How Git tracks your work using the working directory, staging area, and repository

• Core Git commands: add, commit, status, log, reset, restore, rm

• How to work with branches, merge updates, and fix merge conflicts

• How to push, pull, and sync your code with GitHub

• Using stash, revert, and rebase to handle real-world workflows

• How pull requests work and why teams use them

Watch the full course on the freeCodeCamp.org YouTube channel (1-hour watch).

I thought, “I’ll add it later.” But “later” never came.

Weeks turned into months, and my once-simple idea turned into chaos. A developer who joined my project had no idea how to set it up. Even I, the founder, started forgetting why I structured certain parts of the app the way I did.

What was supposed to be a few months of development stretched to nearly a year. All because I ignored one small file: the README.

In this article, you’ll learn how to structure your README file to show all the important information about your project. You can see what it’ll look like here: MybrandName repo.

Table of Contents

• The README File is Not Just a Formality

  • README Structure

• MyBrandName — AI Branding Assistant

  • Features

  • Tech Stack

• Quick Start

  • Prerequisites

  • Installations

• Repository Structure

  • Architecture Overview

  • Example API Endpoints

  • Authentication (Supabase)

  • Environment Variables

  • Testing

  • Continuous Integration (CI)

  • Versioning & Changelog

• Contributing

  • Code of Conduct

• Deployment

  • License

  • The GitHub Repository

  • Developer Checklist

• Common Pitfalls & How to Avoid Them (Beginner-Friendly)

  • Problem: Hardcoding API Keys

  • Problem: No Quick Start Section

  • Problem: Missing Example Requests or Screenshots

  • Problem: Confusing Folder Structure

  • Problem: Forgetting to Version Your Project

  • Problem: No Testing Before Deployment

• 💡 What You Can Learn from This

• Final Words

The README File is Not Just a Formality

Many beginners see the README as optional—something you add just before submitting your GitHub repo. But that’s isn’t the right mindset.

Your README is your project’s map. It tells any developer (including your future self) where to start, how to set up the environment, and how everything connects. It saves time, reduces frustration, and turns a pile of code into a usable, understandable project.

If someone can clone your repository and get it running in under 10 minutes, your README did its job!

README Structure

Your README acts like the user manual for any developer who clones your repository. It should guide a developer to:

• Clone the repo.

• Install dependencies.

• Configure environment variables.

• Run both backend and frontend successfully.

• Understand how the system works.

Let me walk you through a sample README from a project called MyBrandName.

Here’s what the README looks like: https://github.com/nuelcas/mybrandname

MyBrandName — AI Branding Assistant

MyBrandName is an AI-powered platform that helps startups create a complete brand identity—logos, stories, and marketing assets—in minutes.

Features

• AI-Powered Branding – Instantly generate logos, brand stories, and marketing assets using OpenAI.

• Authentication – Secure user login and registration powered by Supabase.

• Database – Supabase for storing users, brands, assets, and subscription data.

• Frontend – Responsive UI built with TypeScript, Vite, and TailwindCSS.

• Backend API – Node.js + Express handles AI generation, authentication, and data management.

• Subscription Management – Stripe integration for plan upgrades and payments.

• Continuous Integration (CI) – Automated testing and build workflows via GitHub Actions.

• Versioning & Changelog – Semantic versioning with a clear project evolution record.

• Deployment Ready – Easily deploy frontend (Vercel) and backend (Render) with Supabase integration.

Tech Stack

• Runtime: Node.js + Express.js.

• Language: TypeScript.

• Frontend: Vite + Tailwind CSS.

• Database & Auth: Supabase (Database, Storage, Authentication).
  AI Service: OpenAI API (Logo, Story, and Content Generation).

• HTTP Client: Axios/Fetch API.

• CI/CD: GitHub Actions (Automated Testing & Deployment).

• Hosting: Vercel (Frontend) + Render (Backend).

Quick Start

Prerequisites

• Node.js 16+

• Supabase project (for Authentication, Database, and Storage)

• OpenAI API key (for AI-powered logo and content generation)

• Stripe account (for subscription and payment handling)

Installations

1. Clone the repository

git clone https://github.com/nuelcas/mybrandname.git

2. Install Dependencies

cd backend && npm install
cd ../frontend && npm install

3. Environment setup

cp backend/.env.example backend/.env

Update .env with your configuration:

• Supabase URL and API key

• OpenAI API key

• Stripe API key

4. Development

# Run backend
cd backend && npm run dev

# Run frontend
cd frontend && npm run dev

5. Production Build

npm run build
npm start

Visit: http://localhost:5173

Repository Structure

/mybrandname
├── /frontend
│   ├── /src
│   │   ├── /components        # UI Components (AuthForm, Navbar, etc.)
│   │   ├── /pages             # App pages (Home, Dashboard, Pricing)
│   │   ├── /hooks             # Custom React hooks (useAuth, useLogoGenerator)
│   │   ├── /lib               # Config files (Supabase, API client, constants)
│   │   ├── /styles            # Global and component styles
│   │   ├── App.tsx            # Main routing setup
│   │   └── main.tsx           # React entry point
│   ├── public/                # Public assets (icons, logos)
│   ├── tailwind.config.ts     # Configures Tailwind CSS settings
│   ├── vite.config.ts         # Contains build and development settings for the Vite bundler
│   └── package.json           # Lists frontend project dependencies, scripts, and metadata
│
├── /backend
│   ├── /src
│   │   ├── /routes            # Express routes (auth, brand, assets, subscription)
│   │   ├── server.ts          # Main Express server entry
│   │   └── config/            # Environment and DB configs
│   └── package.json           # Lists backend project dependencies, scripts, and metadata for Node.js
│
└── README.md

Architecture Overview

Frontend

• Built with TypeScript + Vite + Tailwind CSS

• Connects to Supabase for authentication, backend API for AI generation, and Stripe for payments

Backend

• Built with Node.js + Express

• Handles authentication, AI content generation, and database writes via Supabase

Supabase Tables

Example API Endpoints

Auth Routes

Branding Routes

Example Request:

POST /api/brand/logo
{
  "brandName": "NovaTech",
  "industry": "Tech",
  "style": "Modern Minimal"
}

Example Response:

{
  "logoUrl": "https://supabase.storage/novatech-logo.png",
  "palette": ["#121212", "#FF005C"]
}

Authentication (Supabase)

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  import.meta.env.VITE_SUPABASE_URL,
  import.meta.env.VITE_SUPABASE_KEY
);

Environment Variables

Testing

Use Vitest/Jest for unit testing and Supertest for API routes.

npm run test

Continuous Integration (CI)

CI automatically runs tests when you push new code. This ensures your main branch always stays stable.

Example GitHub Action Workflow:

name: MyBrandName CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: |
          cd backend && npm ci && npm run test
          cd ../frontend && npm ci && npm run build

Tip: CI helps avoid “it works on my machine” problems.

Versioning & Changelog

Keep a CHANGELOG.md file documenting updates.
Use Semantic Versioning (MAJOR.MINOR.PATCH), for example,
1.1.0 → Added new features.

Contributing

We welcome contributions from developers who want to improve MyBrandName!
Follow these steps to contribute effectively:

• Fork the Repository

  • Click the Fork button on GitHub to create your own copy of the project.

• Clone Your Fork

  • Run:

    git clone https://github.com/nuelcas/mybrandname.git

• Create a Feature Branch

  • Keep your changes organized:

    git checkout -b feat/your-feature-name

• Set Up the Environment

  • Follow the setup instructions in the README to install dependencies and configure your .env files.

• Follow Code Style and Formatting Rules

  • Ensure consistent formatting before committing:

    npm run lint

• Use Clear Commit Messages

  • Follow the conventional commit style:

    • feat: – new feature

    • fix: – bug fix

    • docs: – documentation update

    • refactor: – code restructuring

• Write or Update Tests

  • Use Vitest or Jest for unit testing and Supertest for API routes.

  • Run:

    npm run test

• Document Your Changes

  • Update README.md, CHANGELOG.md, or CONTRIBUTING.md if needed.

• Submit a Pull Request (PR)

  • Push your branch and open a PR with:

    • A short, clear description of your changes.

    • Any related issue numbers (for example, “Closes #12”).

    • Screenshots or example outputs (if applicable).

• Participate in Code Review

  • Respond to feedback, make improvements, and help maintain project quality.

Code of Conduct

To maintain a positive and inclusive community, all contributors are expected to:

• Be respectful, kind, and patient when interacting with others.

• Welcome feedback and engage in constructive discussions.

• Avoid discriminatory or offensive language.

• Focus on collaboration and problem-solving rather than criticism.

• Credit other contributors where due.

• Report any violations or concerns to the maintainers privately.

Let’s work together to make MyBrandName a project where everyone feels valued and supported. 💙

Deployment

License

This project is licensed under the MIT License—see the LICENSE file for details.

The GitHub Repository

You can clone the GitHub repo, edit and build your app from it: MybrandName repo.

Developer Checklist

Think of this checklist as your final review before sharing your app publicly:

1. Supabase Authentication is Working

• Test your login and registration flow.

• Try creating a new account and logging in.

• Make sure the user’s data appears correctly in the Supabase “users” table.

2. AI Endpoints Return Proper Results

• Test your backend endpoints for AI-powered features (for example, logo generation).

• Use tools like Postman to send sample requests.

• Confirm that Supabase stores the generated data or files correctly.

3. Frontend is Responsive

• Open your app on a mobile device and desktop browser.

• Ensure the design adjusts properly to different screen sizes.

• Check for broken buttons, misaligned text, or hidden sections.

4. Continuous Integration (CI) Tests Pass

• If you use GitHub Actions, make sure your tests run automatically when you push code.

• Fix any failed tests before merging branches.

• This helps you catch bugs early.

5. Documentation Files Are Complete

• Ensure your README, CONTRIBUTING, and CHANGELOG files are up to date.

• Add setup steps, contribution guidelines, and update notes.

• This makes your repo beginner-friendly and professional.

Run through your README’s Quick Start section as if you’re a new user.
If you can set up the project in less than 10 minutes, your documentation is clear enough.

Common Pitfalls & How to Avoid Them (Beginner-Friendly)

Here are some common mistakes new developers make and how you can prevent them:

Problem: Hardcoding API Keys

Never store API keys directly in your code. If you push your project to GitHub, anyone can see them.

Solution: Store them in a .env file and add .env to .gitignore.

Problem: No Quick Start Section

If your README doesn’t explain how to install and run the app, other developers will be lost.

Solution: Always include a Quick Start section showing installation and setup steps.

Problem: Missing Example Requests or Screenshots

Readers want to see what your API or app does before trying it.

Solution: Add example API requests and responses (like the /api/brand/logo example). You can also include screenshots of the UI.

Problem: Confusing Folder Structure

A messy project makes it hard for contributors to navigate your code.

Solution: Explain your folder structure under “Repository Structure.” Include short descriptions of what each folder does.

Problem: Forgetting to Version Your Project

If you don’t track changes, it’s hard to know what was updated or fixed.

Solution: Use Semantic Versioning (1.0.0, 1.1.0, and so on) and keep a simple CHANGELOG.md file.

Problem: No Testing Before Deployment

Beginners often deploy without testing—and later find bugs in production.

Solution: Run your tests locally first. Automate them using GitHub Actions so that every code change is verified.

By addressing these simple issues early, you’ll build reliable, professional-looking projects that others can understand and contribute to easily.

💡 What You Can Learn from This

A good README file saves you from:

• Wasting hours debugging setup issues

• Confusing collaborators or testers

• Forgetting your own logic months later

It also makes your project look professional to employers and recruiters.

Final Words

When I finally embraced writing detailed README files, everything changed. New collaborators understood my projects faster. Deployment became smoother. And most importantly—I never had to “learn the hard way” again.

So if you’re just starting out, take my advice: Before you write your next line of code, write your README file.

In this tutorial, you’ll to learn what the GitHub CLI is, how to install and set it up, and how to use it for everyday tasks such as creating repositories, managing issues and pull requests, working with GitHub Actions, and automating tasks using custom aliases. You’ll learn how to replace some functionalities on GitHub’s web interface with quick commands in your terminal.

Here’s what we’ll cover:

• Overview of GitHub CLI

• Key Features

• Benefits of Using GitHub CLI

• Installation and Setup

• Authenticating with a GitHub Account

• Navigating the GitHub CLI

• Managing Repositories

• Working with Pull Requests and Issues

• Pushing and Pulling Changes

• Working with GitHub Actions

• Managing Gists

• Releases and Tags

• Custom Scripts and Aliases

• Troubleshooting

• Conclusion

Overview of GitHub CLI

You can use the GitHub CLI to bridge the gap between GitHub's web interface and your local environment. You can perform various tasks such as creating issues, managing repositories, or even checking the status of your GitHub Actions workflows using the CLI. Using the CLI, you can perform almost all the tasks that you might complete on the GitHub website.

Key Features of GitHub CLI

• Repository management: Easily create, clone, view, and manage repositories.

• Pull requests and issues: Manage pull requests and issues directly from the terminal, including creating, merging, and listing them.

• GitHub Actions: Interact with workflows and manage workflow runs.

• Authentication: Provides a secure way to authenticate with your GitHub account, supporting SSH keys, tokens, and OAuth.

• Custom scripting: Lets you create custom scripts and aliases to automate repetitive tasks and streamline development processes.

Benefits of Using GitHub CLI

Suppose you’re working on a project, and you need to create a new issue on GitHub. Normally, you would switch to your browser, log in to GitHub, navigate to the repository, click on the “Issues” tab, and then click “New Issue.” With GitHub CLI, you can do all of this by typing a single command, without ever leaving your terminal. This makes your workflow faster and saves time.

Installation and Setup

To install GitHub CLI on Windows, you can use the winget package manager. Winget is a command-line tool that allows you to install software easily.

Installing GitHub CLI on Windows, macOS, and Linux

Windows:

Run the command given below:

winget install --id GitHub.cli

• winget install: Tells Windows to install a new software package.

• --id GitHub.cli: Specifies the exact package ID for GitHub CLI.

After running this command, GitHub CLI will be installed on your Windows system.

macOS:

You can use Homebrew to install GitHub CLI on macOS. Open your terminal and run:

brew install gh

Linux:

On Linux, you can use your package manager. For example, on Ubuntu, you can run:

sudo apt install gh

Authenticating with a GitHub Account

After installing GitHub CLI, the next step is to authenticate it with your GitHub account.

Run Authentication Command:

Type gh auth login in the terminal and press Enter.

gh auth login

You’ll then be prompted to select an authentication method. The recommended option is to authenticate via a web browser.

If you select the browser method, GitHub CLI will open a link in your default browser, where you can log in to GitHub.

Complete Authentication:

After logging in, the browser will confirm that the GitHub CLI is connected to your account.

You can verify the authentication status by running:

gh auth status

Navigating the GitHub CLI

The GitHub CLI is easy to navigate, and its command structure is intuitive.

Command Structure and Syntax

GitHub CLI commands follow a simple and straightforward pattern:

gh [command] [subcommand] [flags]

• Command: The main action you want to perform (for example, repo, issue, pr).

• Subcommand: A specific task within the command (for example, create, list, view).

• Flags: Optional parameters that modify the command's behavior (for example, --title, --body).

Commonly Used Commands and Flags

Here are some common GitHub CLI commands:

• Creating a repository: gh repo create

• Listing issues: gh issue list

• Creating a pull request: gh pr create

• Viewing a repository's details: gh repo view

To see all available commands and options, you can always run:

gh help

How to Manage Repositories with the GitHub CLI

Let’s go through examples of some of the commands you’ll use the most often.

Creating and Cloning Repositories

To create a new GitHub repository directly from the terminal, just use the following command:

gh repo create my-repo-name

To clone an existing repository, use the following command:

gh repo clone owner/repo-name

Managing Branches and Pull Requests

GitHub CLI allows you to handle issues and pull requests (PRs) without leaving the terminal.

Switching branches or creating pull requests is simple. To create a new branch:

git checkout -b new-branch-name

Then, to create a pull request:

gh pr create --title "Your PR Title" --body "Description of your PR"

Pushing and Pulling Changes

Push your changes to GitHub with this command:

git push origin branch-name

And pull the latest changes with:

git pull

Working with GitHub Actions

GitHub CLI also supports GitHub Actions, allowing you to manage workflows directly from your terminal.

You can manually trigger workflows using the following:

gh workflow run workflow-name

And you can monitor the status of workflows with:

gh run list

To see detailed logs of a workflow, run this:

gh run view run-id --log

Cloning and Forking Repositories

Cloning and forking are essential tasks when working on projects from other repositories.

To clone a repository, use this command:

gh repo clone <repository-name>

To fork a repository, do this:

gh repo fork <repository-url>

Example:

Here’s what it would look like:

gh repo clone example-repo

gh repo fork https://github.com/username/repository-name

How to Work with GitHub Actions

Using the GitHub CLI, you can also manage GitHub Actions, which are automated tasks you can run in response to certain events in your repository.

Triggering and Monitoring Workflows

You can trigger a workflow manually like this:

gh workflow run <workflow-name>

And you can monitor workflow runs with this:

gh run list

Managing Workflow Runs and Logs

If you want to check the details of a specific workflow run, you can view logs directly from the CLI:

gh run view <run-id> --log

You can also use GitHub CLI commands to enhance your Continuous Integration/Continuous Deployment (CI/CD) pipelines, ensuring smooth automation and better control over our workflows.

How to Update the GitHub CLI

To make sure that you’re using the latest version of GitHub CLI with all the latest features and fixes, you can update it using winget.

winget upgrade --id GitHub.cli

• winget upgrade: Checks for updates for the specified package.

• --id GitHub.cli: Identifies the GitHub CLI package for the upgrade.

Advanced GitHub CLI Features and Integrations

The GitHub CLI is not only useful for performing basic tasks. You can also perform some advanced operations with its help.

How to Manage Gists with the GitHub CLI

Gists are a simple way to share snippets of code. You can create, list, and manage your Gists right from the CLI. Here’s how you can create a gist:

gh gist create my-code-snippet.py

To list your gists:

gh gist list

Interacting with Releases and Tags

To manage releases and tags, GitHub CLI provides commands to create, list, and delete releases. Here’s an example of creating a release:

gh release create v1.0.0

How to Extend the GitHub CLI with Custom Scripts and Aliases

You can write your own scripts and integrate them into GitHub CLI, or create aliases for commands you use frequently to save time. Aliases let you create shortcuts for commands that you use often. For example, the command given below creates an alias prlist that will show all pull requests, regardless of their state:

gh alias set prlist "pr list --state all"

In the same manner, you can create a shortcut co to quickly check out a pull request branch without typing the full command each time. The command is given below:

gh alias set co "pr checkout"

Troubleshooting Common Issues

If you face any issues, you can troubleshoot by checking the command syntax, ensuring your GitHub CLI is up to date, or consulting the documentation using the command:

gh help <command>

Conclusion

GitHub CLI is an excellent tool that helps developers work directly from the terminal. It lets you manage repositories, handle pull requests and issues, trigger and monitor GitHub Actions, and even work with Gists.

You can save time and improve productivity as developers using this powerful tool. Keep exploring its new features and stay updated with the latest version.

This is where automation comes in. By combining OpenAPI specifications with GitHub Actions, you can ensure your documentation is always in sync with your API changes.

• OpenAPI acts as the single reference point for your API design, keeping your docs consistent, accurate, and aligned with your API.

• GitHub Actions automates the workflow, validating your spec, building docs, and publishing to GitHub Pages in seconds.

This tutorial walks you through a working example of how to use GitHub Actions to auto-update your docs.

Table of Contents

• Prerequisites

• How to set up your repository

• How to Create the OpenAPI Specification

• How to Test the API Spec Locally

  • Install tools

  • Create a landing page

  • Validate Your Spec

  • Preview in the Browser

• How to Push Local Changes to GitHub

• How to Set Up Your GitHub Actions Workflow

• How to Set Up GitHub Pages

  • What is GitHub Pages?

  • Setting Up GitHub Pages

• How to Handle Multiple Versions

  • About the Versions

    • Version 1 (v1)

    • Version 2 (v2)

    • Version 3 (v3)

  • How to Set Up the Versions Locally

  • How to Validate the API Specs

  • How to Update the GitHub Actions Workflow

• Summary

Prerequisites

• Node.js and npm installed.

• A GitHub account with basic Git knowledge.

• Visual Studio Code Editor.

• Basic knowledge of documentation and OpenAPI.

How to Set Up Your Repository

If you don’t already have one, create a GitHub repository. For this tutorial, I’ll use api-docs as the repo name.

Then open VSCode and create a folder with the same name.

How to Create the OpenAPI Specification

Inside the folder you just created, create a folder called spec and add a file named greetings.yaml with the following content:

openapi: 3.0.3
info:
  title: Greetings API
  version: 1.0.0
  description: This is a greetings API demonstrating a simple greeting endpoint with query parameters and multilingual support.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.yourdomain.com/v1
    description: Production server(v1)
  - url: https://staging.yourdomain.com/v1
    description: Staging server(v1)
security:
  - api_key: []
paths:
  /hello:
    get:
      summary: Returns a greeting
      operationId: getGreeting
      parameters:
        - name: name
          in: query
          required: false
          description: Name of the person to greet
          schema:
            type: string
            example: Ezinne
        - name: lang
          in: query
          required: false
          description: Language of the greeting (default is English)
          schema:
            type: string
            enum: [en, fr, es, ig]
            example: en
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                english:
                  value: { message: "Hello, Ezinne!" }
                french:
                  value: { message: "Bonjour, Ezinne!" }
                spanish:
                  value: { message: "¡Hola, Ezinne!" }
                igbo:
                  value: { message: "Ndeewo, Ezinne!" }
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header

This is a simple spec with multilingual greetings. As your API grows (say more languages or versions), keeping docs in sync manually might get tedious. That’s why automation helps.

How to Test the API Spec Locally

Install tools:

Before setting GitHub Actions, you can test the API Spec locally on your machine by setting up Redocly (used to be called Redoc) and testing it in an HTML environment.

Redocly is a lightweight, customizable tool to render OpenAPI specs as an interactive HTML documentation. It’s ideal for static site deployment which makes it ideal for this scenario.

• Install Redoc globally with npm install -g @redocly/cli

• Install http-server globally with npm install -g http-server

The http-server is a local server you can use to test the doc on your machine before you push to GitHub and deploy to GitHub Pages.

Create a landing page:

In your project, make a docs folder and add index.html:

<!DOCTYPE html>
<html>
  <head>
    <title>API Documentation</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <redoc spec-url="../spec/greetings.yaml"></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
  </body>
</html>

Validate Your Spec:

redocly lint spec/greetings.yaml

You should see this if there are no errors or warnings:

Woohoo! Your API description is valid. 🎉

Note: Validating your API Spec before testing is important as it’ll flag any possible errors. This is because Redocly will fail to run the preview if there are any errors in your spec.

Preview in the browser:

Run http-server, and you should see this in the terminal:

Starting up http-server, serving ./
Available on:
  http://127.0.0.1:8080
  http://192.168.x.x:8080
Hit CTRL-C to stop the server

Open http://127.0.0.1:8080/ and navigate to /docs to see your docs.

How to Push Local Changes to GitHub

After making local changes, you need to set up the API documentation so it can update automatically whenever you make changes.

Run these commands if you are pushing to the repository for the first time:

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin <your-repo-url>
git push -u origin main

How to Set Up Your GitHub Actions Workflow

You can set up your GitHub workflow by creating a few folders.

First, create .github/workflows/ in the api-docs folder. Then, inside the workflows folder, create a docs.yml. This is the workflow file that will serve as a trigger to run validation, generate the HTML with Redocly, and deploy to GitHub Pages at the same time.

name: Build API Documentation and Deploy to GitHub Pages

on:
  push:
    branches:
      - main
    paths:
      - 'spec/greetings.yaml'

jobs:
  build-spec:
    runs-on: ubuntu-latest
    permissions:
      contents: write # needed for gh-pages deployment

    steps:
      # 1. Checkout repository
      - name: Checkout code
        uses: actions/checkout@v4

      # 2. Set up Node.js
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      # 3. Install Redocly CLI
      - name: Install Redocly CLI
        run: npm install -g @redocly/cli

      # 4. Validate OpenAPI spec
      - name: Validate OpenAPI Spec
        run: redocly lint spec/greetings.yaml

      # 5. Build output directory
      - name: Create build directory
        run: mkdir -p public

      # 6. Copy spec
      - name: Copy spec
        run: mkdir -p public/spec && cp spec/greetings.yaml public/spec/

      # 7. Copy landing page
      - name: Copy landing page
        run: cp docs/index.html public/index.html

      # 8. Deploy to GitHub Pages
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Here’s what’s going on in this code:

• Runs when changes are pushed to main that affect spec/greetings.yaml.

• Checks out the repo code.

• Sets up Node.js and installs Redocly.

• Validates your OpenAPI spec (so broken specs won’t deploy).

• Copies the spec and index page into a public/ folder.

• Deploys public/ to the gh-pages branch with GitHub Pages.

Since we’re done with local testing, update the file path in the index.html:

<!DOCTYPE html>
<html>
  <head>
    <title>API Documentation</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <redoc spec-url="./spec/greetings.yaml"></redoc> <!--update the filepath to match your gh config-->
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
  </body>
</html>

This is so the public directory in the workflow will be able to access it correctly.

This workflow will only run when it detects changes in the API Spec (greetings.yml). To see the workflow in action, make a minor edit in the greetings.yaml.

Push the changes to your GitHub repository:

git add .
git commit -m 'add changes'
git push

How to Set Up GitHub Pages

What is GitHub Pages?

GitHub Pages is a hosting platform owned by GitHub where you can host websites directly from your GitHub account. This means you can publish static sites on the internet using a GitHub domain and anyone with the website link can access it.

There are other hosting platforms you can use to deploy static websites such as Netlify and Vercel. But using GitHub Pages for this documentation is easier to set up as it’s on the same platform.

Setting up GitHub Pages

Set up GitHub Pages by clicking on the Settings tab in your repository.

Under Source, choose:

• Deploy from branch: gh-pages

• Folder: / (root)

Then save and wait for the workflow to finish.

Your docs will be live at: https://<username>.github.io/api-docs.

How to Handle Multiple Versions

What if you had multiple API versions to update? Let’s assume the simple greetings API in this tutorial had more features added to it across different versions. In this case, you can manage the APIs for the different versions in a single page and also build and deploy it automatically.

About the Versions

Version 1 (v1)

This is the starting point which is greetings.yaml. The API only has a single /hello endpoint that returns a greeting in four languages (English, French, Spanish, or Igbo).

Version 2 (v2)

In version 2, the API adds create and read features. You can:

• Use POST /hello to create and save a greeting.

• Retrieve greetings by their unique ID with GET /hello/{id}.

Version 3 (v3)

Version 3 builds on top of v2 by adding an update functionality. Along with creating and retrieving greetings, you can now update an existing greeting using PUT /hello/{id}.

How to Set Up the Versions Locally

First, create a v1 folder and move the greetings.yaml file to it. Since we are going to be using versions, you can delete the existing spec folder.

Then, create a v2 folder and create a greetings-v2.yaml file. Get the greetings API for version 2 here.

Next, create a v3 folder and add greetings-v3.yaml file. Get the greetings API for version 3 here.

To follow the same pattern with others, rename the version 1 file to greetings-v1.yaml. Then update your index.html to accommodate the other two versions.

<!DOCTYPE html>
<html>
  <head>
    <title>API Documentation</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style>
      body {
        font-family: Arial, sans-serif;
        margin: 0;
      }
      header {
        background: #2c3e50;
        color: white;
        padding: 1rem;
        display: flex;
        justify-content: space-between;
        align-items: center;
      }
      select {
        padding: 0.4rem;
        font-size: 1rem;
      }
    </style>
  </head>
  <body>
    <header>
      <h2>API Documentation</h2>
      <div>
        <label for="version">Version: </label>
        <select id="version" onchange="loadSpec()">
          <option value="./v1/greetings-v1.yaml">v1</option>
          <option value="./v2/greetings-v2.yaml">v2</option>
          <option value="./v3/greetings-v3.yaml">v3</option>
        </select>
      </div>
    </header>

    <!-- ReDoc container -->
    <div id="redoc-container"></div>

    <!-- ReDoc script -->
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
    <script>
      function loadSpec() {
        const version = document.getElementById("version").value;
        Redoc.init(version, {}, document.getElementById("redoc-container"));
      }
      // Load default (v1) on first load
      window.onload = loadSpec;
    </script>
  </body>
</html>

How to Validate the API Specs

Earlier in this article, I mentioned testing your specification locally. Now that you have two more versions of the greetings API, run the test to highlight and fix any existing errors.

• For the version V2: redocly lint v2/greetings-v2.yaml

• For the version V3: redocly lint v3/greetings-v3.yaml

How to Update the GitHub Actions Workflow

Now that you have three API Spec versions, you need to update your workflow so it will monitor the three spec files and the HTML document for changes, and then push and deploy them to GitHub Pages as well.

Add this to your .github/workflows/docs.yml:

# Name of the workflow
name: Build and Deploy API Documentation

on:
  push:
    branches: [ main ]
    paths:
      - 'docs/index.html'
      - 'v1/greetings-v1.yaml'
      - 'v2/greetings-v2.yaml'
      - 'v3/greetings-v3.yaml'

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: write

    steps:
      # 1. Checkout the repository
      - name: Checkout repository
        uses: actions/checkout@v4

      # 2. Create build directory
      - name: Create build directory
        run: mkdir -p public

      # 3. Copy YAML specs into public folder
      - name: Copy v1 spec
        run: mkdir -p public/v1 && cp v1/greetings-v1.yaml public/v1/

      - name: Copy v2 spec
        run: mkdir -p public/v2 && cp v2/greetings-v2.yaml public/v2/

      - name: Copy v3 spec
        run: mkdir -p public/v3 && cp v3/greetings-v3.yaml public/v3/

      # 4. Copy landing page into public
      - name: Copy landing page
        run: cp docs/index.html public/index.html

      # 5. Deploy to GitHub Pages
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

And finally, push the changes and reload the site. This should showcase the updated documentation.

Summary

In this tutorial, you have learned how to auto-update your API docs. We started with a single OpenAPI spec and a basic HTML page rendered by Redocly, and tested it locally. We then set up GitHub Actions to automatically validate the spec, copy the files, and deploy the docs to GitHub Pages. Finally, we extended the setup to handle multiple API versions in one place.

With this workflow, your documentation stays accurate, up-to-date, and hassle-free so every change you make to your API spec goes live when you push the changes.

In this article, we’ll discuss some common misconceptions that might be holding you back from contributing to open source. I’ll show you what you’re missing out on, and give you some advice to help you begin.

Table of Contents

1. What is Open Source?

2. Key Factors Influencing Open Source Contributions

3. Why People Hesitate to Contribute

   • You feel like an impostor

   • You have to do it for free

   • You have a busy schedule

4. Start Contributing to Open Source Today

What is Open Source?

Open source refers to software that has its code publicly available for viewing, modification, and use. The code is usually hosted on platforms like GitHub where developers can contribute to the codebase and share their expertise with the project.

Although open source software code is publicly accessible, it doesn’t mean that the software has to be free. Creators of the software can make money by charging a fee for things like optional plugins, consultation about the software, and so on.

Nginx is an example of open source software that charges a fee for additional but optional plugins. NestJS is open source too, but has an official paid course (and its maintainers charge a consultation fee for more complex uses of the software).

Key Factors Influencing Open Source Contributions

In 2023, roughly 10% of Alphabet’s full-time workforce actively contributed to open source projects. And according to GitHub’s 2024 Open Source Survey, respondents reported that the top five factors that influenced their contribution to open source projects, in order of importance, were:

• Whether the project had an open source license or not. Having an open source license was considered favourable.

• The responsiveness of the project’s maintainers. Fast and positive responses are encouraging.

• A welcoming community, indicating support from the maintainers and others contributing to the project.

• The level of activity on the project – lots of activity signifies an actively maintained project (which is more rewarding and useful to work on).

• Whether the project had a contribution guide that helps developers ease into contributing to the project.

But even though many projects are attractive, and their maintainers are welcoming, some people still hesitate to contribute for reasons not linked to the projects themselves.

Why People Hesitate to Contribute

After looking into responses from various discussions, I found that there are three primary barriers developers face when they’re considering contributing to open source:

• You feel like an impostor

• You have to do it for free

• You have a busy schedule

The rest of this article will address (and hopefully break down) these barriers. I hope that by the end, you’ll be encouraged to contribute to open source.

You feel like an impostor

Many people think that you have to know a lot about a project to work on it, but this misconception is one of the biggest barriers that holds developers back from contributing to open source. Some people say to themselves “I don't have the experience”, “I have nothing to contribute”, “What if I break something?”, “I don’t know enough”.

Here’s some advice from How to Overcome Imposter Syndrome that can help:

• Stop obsessing over not being good enough. It’s unproductive.

• Everyone excels at different things. You likely excel at some things that others don’t.

• Don’t compare yourself with others who are more experienced than you. In fact, stop comparing yourself with anyone else. You are unique.

Try to contribute to projects that you have used. You already understand them better than projects that you haven’t used. As a beginner, working on issues labeled “good first issue”, “up-for-grabs”, “beginner-friendly” and so on is a great place to start. If you find an issue that interests you, read the discussions under it if there are any so you can understand it better. State that you are interested in working on it and an experienced contributor will likely respond to let you know if you can proceed. They can also provide you with more information if you need it.

Put in the work to resolve it yourself first, and if you have any issues, then you can ask more questions. When you try to resolve it yourself before asking questions, it tells maintainers that you have put in the effort and they will be more willing to help. It also makes your question(s) sound thoughtful and direct.

“The three most powerful motives are curiosity, delight, and the desire to do something impressive. “

— How to Do Great Work by Paul Graham

I shared my experience in an article titled You Don't Need to Know It All to Contribute where I found out that the author of a popular JavaScript project was not the one that wrote the TypeScript part of the project and he was happy to receive my contribution.

If you still feel like you are not good enough, try to look at it as an opportunity to learn from a codebase built by developers with a wide range of experiences and expertise. If you dive into the code and try to improve it, you’ll learn things that you won’t find in online tutorials and blog posts.

Just keep in mind that you don’t always have to contribute code. Even though the majority of contributions are usually code-based, there are other areas that need attention, too, and are often overlooked. What happens if the documentation is nonexistent or outdated? What happens when issues aren’t triaged? You can help with these issues by:

• Discussing them with project maintainers and other contributors to clarify and improve docs and other resources

• Giving feedback on pull requests

• Adding labels for organising issues into proper categories

By doing this, you provide value to these projects. What matters is your interest in solving problems and your ability to do the required research.

You have to do it for free

Another misconception is that devs always do open source without getting paid. But this isn't true for all cases. Some open source repositories reward contributors via bounties, for example. With bounties, prize money is placed on an an issue and whoever solves it gets the prize money or reward. I earned money through this via my first contribution to Remotion.

And there are other benefits of contributing to open source projects aside from getting paid. And often, people contribute primarily for these other reasons.

For example, for beginner developers, there aren’t many opportunities to get hands-on experience building “real” projects, or to learn what working on a tech team is really like.

But by contributing to an open source project and becoming part of that community, you get to practice teamwork, contribute to code that’s constantly changing and growing, and solve real-life problems. This gives you valuable experience that’ll help prepare you for the workforce (and that you can put on your résumé). The image below is a screenshot of two people who received a scholarship from the Linux Foundation for their contributions to open source.

So as you can see, even if you don’t get monetary rewards, contributing to open source presents many other opportunities. You get to:

• Work with people from diverse cultures

• Develop clear written technical communication skills

• Improve your knowledge of various tools/frameworks

• Prove yourself to be a self-motivated developer

• Work asynchronously with people across multiple time zones

You also get the opportunity to network with other developers and grow your reputation and credibility in the software development space. Prosper Otemuyiwa and Anthony Fu are great examples and beneficiaries of this type of career growth.

You have a busy schedule

Having other pressing commitments is a reasonable barrier to contributing to open source. We’re all human, and our resources (time and energy) are limited – so we have to manage them judiciously.

But have you considered what would happen if the open source project that you use had a serious bug that affects your performance or deliverables at work? What happens when the problem you are trying to solve at work requires expert knowledge of that open source project that you heavily depend on?

Contributing to open source projects in the little ways that you can will give you insight into how the projects work. Since you have to maintain a rapport with other developers on the project, you’ll form a professional bond with them and they’ll be glad to help you out if you have questions or require expert opinions on the project. If you are a major contributor, you may have the chance to influence the project’s roadmap.

Continuing to develop your skills is paramount to you as a developer. If you can make time to improve your skills, then you can make time to contribute to open source because it offers more rewards than just skill improvement. You can start small – try dedicating, for example, one hour a week before work, or a couple hours on the weekend. Then you can ramp up once you get into the rhythm and find more time. Contributing to open source doesn’t have to be overly demanding.

You’re already solving problems. Why not solve them in a visible way that helps others and builds your own credibility?

Start Contributing to Open Source Today

We all should contribute to open source one way or another. If you feel that you don’t know enough, just keep in mind that other people feel (or felt, before starting) the same way. And know that nobody can claim to know it all – not even the founder of the project. So don’t let the feeling of impostor syndrome hold you back.

Remember also that Rome was not built in a day. It wasn’t also built by one person’s hand – but by countless laborers over many centuries and millennia. You could be part of building the next great open source project (or helping maintain the many great ones that are already out there and need your help).

So consider contributing today by visiting the issues tab of any of the open source projects that you use extensively and pick up something. You can find links to beginner-level issues from the following websites:

• Good First Issue

• Up For Grabs

• CodeTriage

• OnlyDust

If you see an issue that you are interested in, take the following steps as a new contributor:

• Look for a CONTRIBUTING.md file and read it for guidance on how to contribute

• Clone the repository and set it up locally

• State your intention to work on the issue by making a comment on the issue

Ask a question if an issue is unclear to you and you’ll get guidance.

Good luck on your open source journey!

The error message failed to authenticate via web browser: Too many requests have been made in the same timeframe. (slow_down) appeared on my terminal, while on the web browser, it indicated that the authentication was successful.

I googled and found some workarounds that I tried, but only one worked like a charm!

After finally solving the tricky authentication issue for GitHub CLI on WSL2, I've put together this guide. It's a complete walkthrough for a solution that works, covering everything from a smooth installation to ongoing management.

Table of Contents

• Prerequisites

• How to Install GitHub CLI on WSL2

• How to Authenticate GitHub CLI on WSL2 with Your GitHub Account

• How to Upgrade GitHub CLI on WSL2

• How to Uninstall GitHub CLI on WSL2

• How to Revoke GitHub CLI Access on GitHub

• Final Words

Prerequisites

Before getting started, ensure that you have these installed on your Windows machine:

• WSL2

• A Linux distro

• Windows PowerShell

• Windows Terminal (optional)

To follow the instructions in this article, you can use Windows PowerShell terminal as an administrator.

Alternatively, if you have Windows Terminal installed, you can use the Linux terminal by clicking the ‘down arrow’ icon at the top and selecting the distro.

How to Install GitHub CLI on WSL2

You can use the installation process described here if you use Ubuntu, Debian, or Raspberry Pi OS (apt) distros. For other distros other than those mentioned here, you can walk through the installation process that's available on the GitHub CLI official docs.

To install GitHub CLI in WSL2:

1. Run this command:

    (type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \
        && sudo mkdir -p -m 755 /etc/apt/keyrings \
        && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
        && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
        && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
        && sudo mkdir -p -m 755 /etc/apt/sources.list.d \
        && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
        && sudo apt update \
        && sudo apt install gh -y
   

2. Type your Linux password when you get prompted.

3. Ensure the GitHub CLI is installed by running gh --version command. If the installation is successful, you should see something like this in your terminal:

    gh version 2.76.2 (2025-07-30)
    https://github.com/cli/cli/releases/tag/v2.76.2
   

How to Authenticate GitHub CLI on WSL2 with Your GitHub Account

Before you can use GitHub CLI, you must first authenticate it. You will get an HTTP 401: Bad credentials (https://api.github.com/graphql) error message if you run any GitHub CLI command without authenticating.

To authenticate GitHub CLI with your GitHub account:

1. Run the gh auth login command in your terminal.

2. You will receive several prompts, and you need to choose the methods you prefer. Here’s what I selected in each prompt:

    ? Where do you use GitHub? GitHub.com
    ? What is your preferred protocol for Git operations on this host? HTTPS
    ? How would you like to authenticate GitHub CLI? Login with a web browser
   

   After answering all prompts, you should get the message to copy a one-time code as shown below. You don’t need to copy the code at this point.

    ! First copy your one-time code: XXXX—XXXX
   

3. Press ‘Enter’. It automatically opens the "Device Activation" page on your browser.

4. Click the green ‘Continue’ button.

   

   GitHub should ask you to enter the code displayed on your terminal, as shown in the screenshot below. But here’s the trick! Don’t paste any code, and don’t close the browser. Let’s first get back to your terminal.

   

   Now you might get this error message on your terminal:

    grep: /proc/sys/fs/binfmt_misc/WSLInterop: No such file or directory
    WSL Interopability is disabled. Please enable it before using WSL.
    grep: /proc/sys/fs/binfmt_misc/WSLInterop: No such file or directory
    [error] WSL Interoperability is disabled. Please enable it before using WSL.
   

5. Press Ctrl + C to stop the process if it's still running, or let it stop by itself. Once it's stopped, you should see this message:

    failed to authenticate via web browser: Too many requests have been made in the same timeframe. (slow_down)
   

6. Run the gh auth login command again and repeat the process to select the methods of your choice. This time, when it asks you to press ‘Enter’, don’t press it.

7. Copy the latest code and return to the "Device Activation" page that you left open in your browser.

8. Paste the code that you copied and click the green ‘Continue’ button.

9. Click the green ‘Authorize github’ button after GitHub redirects you to the “Authorize GitHub CLI” page. You should now see the message “Congratulations, you're all set!”

10. Get back to your terminal and press ‘Enter’. Doing so triggers these actions:

    • It automatically opens a new “Device Activation” page in your browser. You can safely ignore this.

    • In the terminal, you first see the error message as in step 4. Don’t do anything and wait for a little bit. Then, you get:

        ✓ Authentication complete.
        - gh config set -h github.com git_protocol https
        ✓ Configured git protocol
        ! Authentication credentials saved in plain text
        ✓ Logged in as YOUR-GITHUB-USERNAME
        ! You were already logged in to this account
      

And GitHub CLI is now successfully authenticated!

Credit goes to username “ikeyan” on GitHub for their GitHub CLI authentication solution!

How to Upgrade GitHub CLI on WSL2

It’s always a good practice to regularly check for package and dependency updates, and upgrade to the newest version when it’s available — this includes GitHub CLI. To check for updates and upgrade the version of GitHub CLI:

1. Run the sudo apt update command in your terminal. This command fetches the list of available updates.

2. Type your Linux password when you get prompted.

3. If you need to upgrade your GitHub CLI, run sudo apt install gh. This command installs the newest version of GitHub CLI.

4. Type your Linux password when you get prompted.

Now your GitHub CLI has the newest version.

How to Uninstall GitHub CLI on WSL2

If one day you feel like you don’t need to use GitHub CLI anymore, you can uninstall it by following these steps:

1. Run the sudo apt remove gh command in your terminal.

2. Type your Linux password when you get prompted.

3. Press ‘Y’ to continue the uninstall process.

GitHub CLI is now uninstalled from your WSL environment.

How to Revoke GitHub CLI Access on GitHub

After uninstalling the GitHub CLI, you might think your account access is gone, but it's not. The authentication you granted is still active. If you don't plan on using the CLI again, it's a good practice to revoke this access.

Here's how to do it directly from your GitHub account:

1. On your GitHub account, click your profile picture on the top right and click ‘Settings’.

   

   2. On the left side bar, find ‘Integrations’ and click ‘Applications’.

      

   3. Click the ‘Authorized OAuth Apps’ tab on top.

      

   4. Find GitHub CLI and click the ‘three dots’ icon next to it.

   5. Click ‘Revoke’.

      

   6. Confirm it by clicking the ‘I understand, revoke access’ button.

Now, GitHub CLI doesn’t have access to your GitHub account.

Final Words

🖼️ Credit cover image: undraw.co

Thank you for reading! Last, you can find me on X and LinkedIn. Let's connect! 😊

If you haven’t heard about what’s going on:

GitHub is struggling to contain an ongoing attack that’s flooding the site with with millions of code repositories. These repositories contain obfuscated malware that steals passwords and cryptocurrency from developer devices. … The result is millions of forks with names identical to the original one.

– Dan Goodin, Ars technica

Because search engines and GitHub’s own search rankings favor recent activity, these cloned repositories often float to the top – then they lure unsuspecting developers into pulling code that may contain malware.

One of my repositories has been targeted by such an attack, prompting me to monitor it closely. This guide offers tips to spot malicious repository clones before they catch you off guard.

Table of Contents

1. What is a Repository Confusion Attack?

   • Supply Chain Attacks

2. 🛡️ Basic Mitigation Strategies

   • Verify the contributors profiles

   • Search for clone repositories

   • Examine the commit pattern

   • Examine the commit history

   • Examine the commit contents

   • Compare the concerned files

   • Some information about the malware

3. Action Time

4. Conclusion

5. More Resources

What is a Repository Confusion Attack?

A repository confusion attack involves:

• Cloning legitimate repositories.

• Injecting malicious code into the clone.

• Uploading the clone.

• Spreading through various unaware actors.

Supply Chain Attacks

If you search for repository confusion on the internet, you'll find out it's a type of supply chain attack.

A supply chain attack is an indirect threat where hackers try infiltrating a system by targeting a trusted third-party or software component, rather than attacking the primary target directly.

It's not the first time this has happened. Before GitHub was targeted, PyPI was attacked in 2023 with fake packages posing as legitimate. These packages lured negligent pip users into downloading malicious payloads (containing in most cases infostealer malware).

🛡️ Basic Mitigation Strategies

Before using any repository, make sure you follow these steps and take these precautions.

Verify the contributors profiles

That's a first check: if you see a rather empty GitHub profile – one without reputation that contains just one repository but with a lot of daily commits to it – well, that's a bit suspicious.

In the fake repository, the original author will be listed as a contributor, too. Check that profile. You should be able to find the legitimate repository and do some comparisons.

In the above screenshot you can see solotech143, my evil doppelgänger (he’s been taken down since).

Search for clone repositories

You can do a GitHub search by repository name and sort the results by most recent first. Malicious repositories tend to appear at the top of the search results because they are updated more frequently. The original repository might be hidden deeper in the search results.

It’s like clone wars.

This is where it’s dangerous: users generally click on the first few search results, and in that type of attack, you’re almost guaranteed to see the attacker’s fake repository at the top of the results. The attacker achieves that by giving the fake repository regular fresh commits (and sometimes even a few stars!).

In my case, the original repository is a submission for the HackaViz 2025 competition. Hackathons offer a good attack surface because, beyond the fact they draw niche communities, they are also time sensitive.

Now, let’s move forward a year and imagine Hackaviz 2026 is starting soon. The attacker has easily outranked the untouched original submission. Which repository is most likely to be visited when future competitors – unaware of the scam – will look for the previous submissions?

Examine the commit pattern

Here’s when things take a weird turn. Malicious clones are run by automated agents, so the commit history fits a pattern that is rather unusual for a human. Of course, you can automate for many legitimate reasons but… this will always follow a clear goal and there will always be a human-touch at some point. In this case, commits are not adding up.

Let's see how that looks in the screenshots below:

Regular like a clock...

... and hyperactive!

Examine the commit history

You can’t! And that's the weird part. You're just able to see the last and the initial commit. So why is it hiding all of them? Do you like it when someone hide things from you?

For July 10th, we should be able to see 11 commits, where are the ten others?

Well, you can only check the first and last commit. That is not a lot for a repository that has more than 2000 commits registered.

Examine the commit contents

Well, since I can always check the last commit, I checked some of them. They share the same pattern: the bot is constantly looping over the README file doing the same modifications. As you can see in the screenshot below, it’s updating the file with links to an infected release.

Above you can see an AI agent stuck in the Readme loop of change.

Human edits are more varied. In a human-driven project, you will see a large mix of commits: feature commits, exploratory experiments, bug fixes, styling tweaks, and sometimes reverts. A bot clone will often just overwrite files, bump versions, or re-inject the same malicious payload repeatedly with no real contribution to the codebase.

Compare the concerned files

This is where common sense comes handy. So, you have two README's:

1. The first consists of AI-generated content that is cluttered with emojis and low-value information. It is designed solely to entice you into clicking the download link of the release.

2. The other follows best practices for creating a good README file. It is accurate and well-structured and functions as a valuable helper and explainer to the code. It also goes deep into the most important aspects of the project. This is usually a good sign that a repository is organic and genuine.

Some information about the malware

What do we have so far? Well, a suspicious link in a phishy, AI-generated README file that is consistent with a very suspicious pattern in the commit history.

Now, let’s have a closer look at that dubious release and let’s see what an online antivirus scanner might reveal about it.

The malware is packed only in the miniature-fortnight-v1.7.6.zip release.

Above you can see the result of a scan with an online scanner.

The .zip file contains only four files:

• config.txt

• launch.bat

• lua51.dll

• luajit.exe

These files are totally unrelated to the source project (a Python data science project with Jupyter notebooks combined to a React app using three.js).

I will not go into the detail in this article. But for the curious ones, it's an infostealer malware (a malware that will exfiltrate your credentials and other precious information about your configuration) similar to the one described in detail here.

Action Time

If you discover a potentially malicious repository, here are some steps you can take:

1. Document some evidence.

2. Notify the original repository maintainers.

3. Report the malicious clone to GitHub.

Reporting a repository or a profile on GitHub is easy and fast. Go to the user’s profile page, click “Block or report” in the left sidebar and choose “Report abuse” in the pop-up. You will have to complete a short contact form with some details about the behavior before submitting. If needed, you can find more information on GitHub.

Conclusion

This is a description of just one attack, from the perspective of someone who found out that one of his repository had been targeted. There are likely cases of more sophisticated attacks. But the clone repository flood we can see on GitHuB is definitely massive low quality automation. Quantity over quality.
To be honest, I'm quite surprised algorithms crafted at GitHub didn't manage to spot this one.

This also raises questions related to AI.

• What happens when LLMs are trained on malicious content? That’s a more general question about AI poisoning.

• A human might easily spot the patterns and the low quality content for now. But..

  • Imagine you are using coding agents, many of them. Will the agents pick-up the malicious clone instead of the original one? How to distinguish the repositories from an automaton's perspective?

  • The attackers will refine their tactics, making the clones more human-like and therefore luring us more easily into their traps.

• This is really a situation that makes me wonder about the early days of Google. Back then, the company had to fight huge amounts of spam due to keyword stuffing and manipulative SEO tactics. Will big tech companies have to go through a Florida update moment to face the rise of AI generated spam ?

More Resources

• A detailed description of the attack

• Complete safety recommendations

Stay Informed, Stay Secure!

A cheat-sheet is also available on my GitHub. Feel free to contribute to it!

In a previous article, we built a Next.js portfolio blog. Here, you’ll learn how to deploy it on Vercel with GitHub Actions.

Prerequisites

To be able to deploy your project, you should have a GitHub repository of the project (you can still follow along if you already have a Next.js project), and a Vercel account. Here is the GitHub repository that we’ll be working with. You can clone it to follow along.

How to Deploy Your Next App

Create Vercel Token and Add it to Your Secrets in GitHub

In your Vercel account, go to Settings, then go to Tokens.

In the Create Token section, enter a name for your token, select an expiration date and click “create”.

You should see a success message with your token. Next, go to your GitHub repository, and click on the “Settings“ tab.

In the Settings tab, go to Secrets and Variables on the sidebar, then click on Actions.

You’ll see a section for adding secrets. Add a secret named VERCEL_TOKEN, and paste the token there.

The Vercel token is a token used to authenticate the GitHub runner. The Vercel CLI installed on the GitHub runner is going to execute the commands with your account. So, instead of it having to login, it uses the access token to verify that it was actually authorized by you to take the actions.

The Organization ID is used to tell Vercel which organization or team account the project should be created under.

The Project ID then tells Vercel the specific project you want to deploy. Just like the Organization ID, it is a unique identifier.

Install the Vercel CLI and Login

Use the command below to install vercel CLI globally on your computer:

npm install -g vercel

Then log into the CLI with the following command:

vercel login

Use one of the options to login.

I used GitHub. Select one with your arrow keys, and click enter.

Create a Vercel Project from Your Local Directory

Navigate to your project directory if you’re not already in it. If you have already created a project on Vercel through the web interfce, use the vercel link command to link your current directory to the Vercel project. If you don’t already have a Vercel project, just type vercel in the CLI and follow the prompts to setup the project.

With that, Vercel will create a .vercel folder in the project. Open it, and go to the project.json file.

In the file, you should see your project ID and organization ID. Copy them and create secrets in your GitHub repository for each one.

Create your GitHub Workflow File

At the root of your project folder, create the .github/workflow folder. Then create a workflow file called vercel_deploy.yml.

In the file, write this:

name: Vercel Production Deployment
env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
on:
  push:
    branches:
      - main
    paths:
      - '01-simple-blog/**'  

jobs:
  Deploy-Production:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: 01-simple-blog
    steps:
      - uses: actions/checkout@v2

      - name: Install Vercel CLI
        run: npm install --global vercel@latest

      - name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build Project Artifacts
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
        continue-on-error: true

      - name: Deploy Project Artifacts to Vercel
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

This is the workflow file for my simple-writer-portfolio project.

First, we have the environment variables:

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
# Other code

Then we have the trigger. This triggers when I push to the main branch, affecting files in the 01-simple-blog subdirectory.

# Previous code
on:
  push:
    branches:
      - main
    paths:
      - '01-simple-blog/**'  
# Other code

Then we have the job definition. Here, I defined a job “Deploy-Production” that runs on Ubuntu. By default, all commands there will run in the 01-simple-blog directory, which is equivalent to running cd 01-simple-blog from the root before running commands on the shell. I did this because the Next.js project is in that directory, where the package.json is located.

# Previous code
jobs:
  Deploy-Production:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: 01-simple-blog
# Other code

Then the steps involved:

# Previous code
 steps:
      - uses: actions/checkout@v2

      - name: Install Vercel CLI
        run: npm install --global vercel@latest

      - name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}

      - name: Build Project Artifacts
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
        continue-on-error: true

      - name: Deploy Project Artifacts to Vercel
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

With these steps, Vercel is first installed on the GitHub runner. Then the vercel environment information is pulled. The project is built with vercel build, and the pre-built artifacts are then pushed to Vercel.

Push to GitHub and watch your code deploy

Stage your changes, if any:

git add .

Commit the changes:

git commit -m "Added GitHub Actions workflow"

And push:

git push origin

Now, go to your repository online, and check the deployment.

Conclusion

With your basic GitHub workflow in place, you can now make changes to your code, push to GitHub, and have it deploy automatically. Though Vercel allows you to connect your repository directly, this method provides you with more flexibility and customizability. If you enjoyed this article, share it with others. You can also reach me on LinkedIn or X.