> ## Documentation Index
> Fetch the complete documentation index at: https://docs.handauncle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Git Fundamentals

> Essential Git concepts and terminology explained

<Info>
  **Start here if you're new to Git** or need a refresher on core concepts like rebase, merge, conflicts, and branching.
</Info>

This guide explains the fundamental Git concepts you'll encounter in our workflow.

***

## What is Git?

Git is a **version control system** that tracks changes to your code over time. Think of it as:

* A time machine for your code
* A collaboration tool that lets multiple people work on the same codebase
* A safety net that lets you experiment without fear

***

## Core Concepts

### Repository (Repo)

A **repository** is a folder containing your project files plus Git's tracking data (stored in `.git/` folder).

<CodeGroup>
  ```bash Example theme={null}
  /Users/aman/Desktop/Handa Uncle/backend/  ← This is a repository
  ```
</CodeGroup>

### Commit

A **commit** is a snapshot of your code at a specific point in time. Each commit:

* Has a unique ID (hash like `a3f2b9c`)
* Contains a message describing what changed
* Records who made the change and when

<CodeGroup>
  ```bash Making a commit theme={null}
  git add .
  git commit -m "feat(api): add user search endpoint"
  ```
</CodeGroup>

<Tip>
  Think of commits as save points in a video game—you can always go back to any commit.
</Tip>

### Branch

A **branch** is an independent line of development. It's like creating a parallel universe where you can make changes without affecting the main timeline.

<CardGroup cols={2}>
  <Card title="main branch" icon="code-branch">
    The stable, production-ready version of your code
  </Card>

  <Card title="feature branch" icon="code-branch">
    Your experimental workspace for new features
  </Card>
</CardGroup>

<CodeGroup>
  ```bash Creating a branch theme={null}
  git checkout -b feature/my-new-feature
  ```
</CodeGroup>

***

## Key Operations Explained

### Clone

**Cloning** downloads a repository from GitHub/GitLab to your local machine.

<CodeGroup>
  ```bash Clone a repository theme={null}
  git clone https://github.com/username/repo.git
  ```
</CodeGroup>

### Pull

**Pulling** downloads the latest changes from the remote repository to your local branch.

<CodeGroup>
  ```bash Pull latest changes theme={null}
  git pull origin main
  ```
</CodeGroup>

<Info>
  Always pull before starting new work to ensure you have the latest code.
</Info>

### Push

**Pushing** uploads your local commits to the remote repository (GitHub/GitLab).

<CodeGroup>
  ```bash Push your changes theme={null}
  git push origin feature/my-feature
  ```
</CodeGroup>

### Add (Staging)

**Adding** files puts them in the "staging area"—marking them to be included in the next commit.

<CodeGroup>
  ```bash Stage files theme={null}
  git add file1.ts file2.ts    # stage specific files
  git add .                     # stage all changed files
  ```
</CodeGroup>

***

## Merge vs Rebase

These are two ways to integrate changes from one branch into another. Understanding the difference is crucial.

### Merge

<Accordion title="What is Merge?">
  **Merge** combines two branches by creating a new "merge commit" that has two parents.

  **Visual:**

  ```
  main:     A---B---C---D
                       /
  feature:        E---F

  After merge:
  main:     A---B---C---D---G (merge commit)
                       /   /
  feature:        E---F---
  ```

  **Characteristics:**

  * Preserves complete history
  * Creates a merge commit
  * Non-destructive (doesn't rewrite history)
  * Can create a "messy" history with lots of branches
</Accordion>

<CodeGroup>
  ```bash Merge example theme={null}
  git checkout main
  git merge feature/my-feature
  ```
</CodeGroup>

### Rebase

<Accordion title="What is Rebase?">
  **Rebase** moves your branch's commits to the tip of another branch, rewriting history to be linear.

  **Visual:**

  ```
  main:     A---B---C---D
                 \
  feature:        E---F

  After rebase:
  main:     A---B---C---D
                         \
  feature:                E'---F' (new commits)
  ```

  **Characteristics:**

  * Creates a clean, linear history
  * Rewrites commit history (new commit IDs)
  * Makes it look like you branched from the latest code
  * Preferred for feature branches before merging
</Accordion>

<CodeGroup>
  ```bash Rebase example theme={null}
  git checkout feature/my-feature
  git rebase main
  ```
</CodeGroup>

<Warning>
  **Never rebase commits that have been pushed to a shared branch** that others are working on. Only rebase your own feature branches.
</Warning>

### When to Use Each

<CardGroup cols={2}>
  <Card title="Use Merge When" icon="code-merge">
    * Merging feature branches into `main`
    * You want to preserve exact history
    * Working on shared branches
  </Card>

  <Card title="Use Rebase When" icon="rotate">
    * Updating your feature branch with latest `main`
    * You want clean, linear history
    * Working on your own feature branch
  </Card>
</CardGroup>

***

## Understanding Merge Conflicts

### What is a Merge Conflict?

A **merge conflict** happens when Git can't automatically combine changes because two people edited the same lines of code differently.

<Info>
  Conflicts are **normal** and not a sign you did something wrong—they're just Git asking you to make a decision.
</Info>

### Conflict Markers Explained

When a conflict occurs, Git marks the conflicting sections in your files:

<CodeGroup>
  ```typescript Conflict markers theme={null}
  <<<<<<< HEAD (your current branch)
  const apiUrl = "http://localhost:8080";
  =======
  const apiUrl = "https://api.production.com";
  >>>>>>> feature/update-api-url (incoming changes)
  ```
</CodeGroup>

**Breaking it down:**

<Steps>
  <Step title="<<<<<<< HEAD">
    Everything between this and `=======` is **your current code** (what's in your branch right now)
  </Step>

  <Step title="=======">
    This line **separates** the two conflicting versions
  </Step>

  <Step title=">>>>>>> branch-name">
    Everything between `=======` and this is the **incoming code** (what you're trying to merge in)
  </Step>
</Steps>

### Resolving Conflicts

<Steps>
  <Step title="Open the conflicting file">
    Your editor will show the conflict markers
  </Step>

  <Step title="Decide what to keep">
    You have three options:

    * Keep your version
    * Keep their version
    * Combine both (manually edit)
  </Step>

  <Step title="Remove conflict markers">
    Delete the `<<<<<<<`, `=======`, and `>>>>>>>` lines
  </Step>

  <Step title="Save and stage the file">
    ```bash theme={null}
    git add conflicted-file.ts
    ```
  </Step>

  <Step title="Continue the merge/rebase">
    ```bash theme={null}
    git rebase --continue  # if rebasing
    # or
    git commit             # if merging
    ```
  </Step>
</Steps>

<CodeGroup>
  ```typescript Example resolution theme={null}
  // Before (with conflict)
  <<<<<<< HEAD
  const apiUrl = "http://localhost:8080";
  =======
  const apiUrl = "https://api.production.com";
  >>>>>>> feature/update-api-url

  // After (resolved - keep production URL)
  const apiUrl = "https://api.production.com";
  ```
</CodeGroup>

***

## Common Git Terms

<AccordionGroup>
  <Accordion title="HEAD">
    A pointer to the current branch and commit you're on. Think of it as "you are here" marker.

    ```bash theme={null}
    HEAD → main → commit abc123
    ```
  </Accordion>

  <Accordion title="Origin">
    The default name for the remote repository (usually on GitHub/GitLab).

    ```bash theme={null}
    origin → https://github.com/username/repo.git
    ```
  </Accordion>

  <Accordion title="Remote">
    A version of your repository hosted on a server (like GitHub). You can have multiple remotes.
  </Accordion>

  <Accordion title="Working Directory">
    The actual files on your computer. This is where you edit code.
  </Accordion>

  <Accordion title="Staging Area (Index)">
    A intermediate area where you prepare files before committing. Files go here when you `git add`.
  </Accordion>

  <Accordion title="Fast-forward">
    A type of merge where Git can simply move the branch pointer forward (no merge commit needed).

    ```
    main:     A---B
                   \
    feature:        C---D

    After fast-forward merge:
    main:     A---B---C---D (no merge commit)
    ```
  </Accordion>

  <Accordion title="Squash">
    Combining multiple commits into one. Often used when merging feature branches to keep `main` clean.

    ```
    feature: A---B---C---D

    After squash merge to main:
    main: X (one commit containing all changes from A, B, C, D)
    ```
  </Accordion>

  <Accordion title="Cherry-pick">
    Copying a specific commit from one branch to another.

    ```bash theme={null}
    git cherry-pick abc123  # apply commit abc123 to current branch
    ```
  </Accordion>

  <Accordion title="Stash">
    Temporarily saving uncommitted changes so you can switch branches.

    ```bash theme={null}
    git stash        # save changes
    git stash pop    # restore changes
    ```
  </Accordion>

  <Accordion title="Detached HEAD">
    When HEAD points directly to a commit instead of a branch. Usually happens when checking out a specific commit.

    ```bash theme={null}
    git checkout abc123  # creates detached HEAD state
    ```
  </Accordion>
</AccordionGroup>

***

## Git Workflow Diagram

```mermaid theme={null}
graph LR
    A[Working Directory] -->|git add| B[Staging Area]
    B -->|git commit| C[Local Repository]
    C -->|git push| D[Remote Repository]
    D -->|git pull| A
    D -->|git fetch| C
```

<Steps>
  <Step title="Edit files">
    Make changes in your working directory
  </Step>

  <Step title="Stage changes">
    Use `git add` to stage files
  </Step>

  <Step title="Commit">
    Use `git commit` to save snapshot
  </Step>

  <Step title="Push">
    Use `git push` to upload to remote
  </Step>
</Steps>

***

## Common Scenarios

### Scenario 1: Update Your Feature Branch

<Info>
  You're working on `feature/my-feature` and `main` has new commits. You want the latest changes.
</Info>

<CodeGroup>
  ```bash Using rebase (recommended) theme={null}
  git checkout feature/my-feature
  git fetch origin
  git rebase origin/main
  ```

  ```bash Using merge (alternative) theme={null}
  git checkout feature/my-feature
  git fetch origin
  git merge origin/main
  ```
</CodeGroup>

### Scenario 2: Undo Last Commit (Not Pushed)

<CodeGroup>
  ```bash Keep changes, undo commit theme={null}
  git reset --soft HEAD~1
  ```

  ```bash Discard changes and commit theme={null}
  git reset --hard HEAD~1
  ```
</CodeGroup>

<Warning>
  `--hard` permanently deletes your changes. Be careful!
</Warning>

### Scenario 3: Save Work in Progress

<CodeGroup>
  ```bash Stash your changes theme={null}
  git stash save "work in progress on login feature"

  # Switch branches, do other work...

  # Come back and restore
  git stash pop
  ```
</CodeGroup>

### Scenario 4: See What Changed

<CodeGroup>
  ```bash View uncommitted changes theme={null}
  git diff

  # View changes in a specific file
  git diff src/index.ts

  # View staged changes
  git diff --staged
  ```
</CodeGroup>

***

## Quick Reference

<CardGroup cols={2}>
  <Card title="Check Status" icon="list-check">
    ```bash theme={null}
    git status
    ```

    See what files are changed, staged, etc.
  </Card>

  <Card title="View History" icon="clock-rotate-left">
    ```bash theme={null}
    git log
    git log --oneline
    ```

    See commit history
  </Card>

  <Card title="Create Branch" icon="code-branch">
    ```bash theme={null}
    git checkout -b feature/new
    ```

    Create and switch to new branch
  </Card>

  <Card title="Switch Branch" icon="arrow-right-arrow-left">
    ```bash theme={null}
    git checkout main
    ```

    Switch to existing branch
  </Card>

  <Card title="Delete Branch" icon="trash">
    ```bash theme={null}
    git branch -d feature/old
    ```

    Delete local branch
  </Card>

  <Card title="Discard Changes" icon="rotate-left">
    ```bash theme={null}
    git checkout -- file.ts
    ```

    Undo uncommitted changes
  </Card>
</CardGroup>

***

## Next Steps

Now that you understand Git fundamentals, learn our team workflows:

<CardGroup cols={2}>
  <Card title="Git Workflow Guide" icon="diagram-project" href="/contributing/git-workflow">
    Learn our branching strategy and merge practices
  </Card>

  <Card title="Commit Message Guide" icon="code-commit" href="/contributing/commit-guide">
    Follow our commit message conventions
  </Card>
</CardGroup>

<Check>
  Understanding these fundamentals will make you confident with Git and help you collaborate effectively.
</Check>