From 14ecc9c67fdc9b8c626f109c5d906245a87d27e0 Mon Sep 17 00:00:00 2001 From: Ajay Dhangar Date: Sat, 11 Apr 2026 19:54:14 +0530 Subject: [PATCH] added git docs --- .../collaboration/_category_.json | 9 ++ .../collaboration/clone.mdx | 82 ++++++++++++ .../collaboration/fork.mdx | 72 +++++++++++ .../collaboration/index.mdx | 1 - .../collaboration/oss-licenses.mdx | 71 +++++++++++ .../collaboration/pull-and-push.mdx | 80 ++++++++++++ .../collaboration/pull-requests.mdx | 82 ++++++++++++ .../collaboration/resolving-conflicts.mdx | 104 +++++++++++++++ .../collaboration/sync-and-upstream.mdx | 102 +++++++++++++++ .../more-git/_category_.json | 9 ++ .../more-git/cherry-picking.mdx | 84 ++++++++++++ .../more-git/git-hooks.mdx | 65 ++++++++++ .../git-github-beginner/more-git/index.mdx | 1 - .../more-git/rebase-merge-squash.mdx | 120 ++++++++++++++++++ .../more-git/reset-and-revert.mdx | 88 +++++++++++++ .../git-github-beginner/more-git/stashing.mdx | 95 ++++++++++++++ 16 files changed, 1063 insertions(+), 2 deletions(-) create mode 100644 absolute-beginners/git-github-beginner/collaboration/_category_.json create mode 100644 absolute-beginners/git-github-beginner/collaboration/clone.mdx create mode 100644 absolute-beginners/git-github-beginner/collaboration/fork.mdx delete mode 100644 absolute-beginners/git-github-beginner/collaboration/index.mdx create mode 100644 absolute-beginners/git-github-beginner/collaboration/oss-licenses.mdx create mode 100644 absolute-beginners/git-github-beginner/collaboration/pull-and-push.mdx create mode 100644 absolute-beginners/git-github-beginner/collaboration/pull-requests.mdx create mode 100644 absolute-beginners/git-github-beginner/collaboration/resolving-conflicts.mdx create mode 100644 absolute-beginners/git-github-beginner/collaboration/sync-and-upstream.mdx create mode 100644 absolute-beginners/git-github-beginner/more-git/_category_.json create mode 100644 absolute-beginners/git-github-beginner/more-git/cherry-picking.mdx create mode 100644 absolute-beginners/git-github-beginner/more-git/git-hooks.mdx delete mode 100644 absolute-beginners/git-github-beginner/more-git/index.mdx create mode 100644 absolute-beginners/git-github-beginner/more-git/rebase-merge-squash.mdx create mode 100644 absolute-beginners/git-github-beginner/more-git/reset-and-revert.mdx create mode 100644 absolute-beginners/git-github-beginner/more-git/stashing.mdx diff --git a/absolute-beginners/git-github-beginner/collaboration/_category_.json b/absolute-beginners/git-github-beginner/collaboration/_category_.json new file mode 100644 index 0000000..7a79dd9 --- /dev/null +++ b/absolute-beginners/git-github-beginner/collaboration/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Collaboration", + "position": 5, + "link": { + "type": "generated-index", + "title": "Collaboration & Open Source", + "description": "Learn the social side of coding. Master Pull Requests, solve conflicts, and contribute to global projects at CodeHarborHub. Discover how to collaborate effectively, manage branches, and navigate the world of open-source development. Join us on this journey to become a confident collaborator in the coding community." + } +} \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/collaboration/clone.mdx b/absolute-beginners/git-github-beginner/collaboration/clone.mdx new file mode 100644 index 0000000..74aee67 --- /dev/null +++ b/absolute-beginners/git-github-beginner/collaboration/clone.mdx @@ -0,0 +1,82 @@ +--- +title: "Cloning a Repository" +sidebar_label: "2. Cloning" +sidebar_position: 2 +description: "Learn how to download a repository from GitHub to your local computer to start coding. This is the essential next step after forking a project and is crucial for contributing to open-source software. Master the cloning process to bring code from the cloud to your machine and begin your development journey." +tags: ["git", "github", "cloning", "open-source", "contributing"] +keywords: ["git", "github", "cloning", "open-source", "contributing"] +--- + +Once you have a repository on GitHub (either your own or a **Fork** you made), the next step is to bring that code onto your physical computer. This process is called **Cloning**. + +When you clone a repository, you aren't just downloading the files; you are downloading the **entire project history** and setting up a connection between your computer and the cloud. + + +## What happens during a Clone? + +Unlike a simple "Download ZIP," `git clone` does three things automatically: +1. **Creates a folder** with the project name. +2. **Downloads every version** of every file in the project's history. +3. **Sets up a Remote** called `origin`, which points back to GitHub so you can push and pull changes later. + +## How to Clone a Project + +To clone a repository, you need its **URL**. You can find this on the main page of any GitHub repository. + +### Step 1: Get the URL +1. Go to the repository on GitHub. +2. Click the green **`<>` Code** button. +3. Copy the **HTTPS** URL (it looks like `https://github.com/user/repo.git`). + +### Step 2: Run the Command +Open your terminal (or Git Bash) and type `git clone` followed by the URL you copied: + +```bash +git clone https://github.com/codeharborhub/tutorial.git +``` + +### Step 3: Enter the Project + +After the download finishes, you must move into the new folder before you can start working: + +```bash +cd tutorial +``` + +## Comparison: Clone vs. Download ZIP + +| Feature | Git Clone | Download ZIP | +| :--- | :--- | :--- | +| **Files** | Yes | Yes | +| **History** | Yes (Every commit ever made) | No (Only current files) | +| **Updates** | Easy (`git pull`) | Must download whole ZIP again | +| **Contribution**| Ready to Push/PR | Not connected to Git | + +## Common Use Cases + +| Scenario | What to do? | +| :--- | :--- | +| **Joining a Team** | Get the project URL from your lead and `git clone` it. | +| **Switching PCs** | `git clone` your own repo to your new laptop. | +| **Learning Open Source** | Find a cool repo, `fork` it, then `clone` your fork. | + +## Cloning with VS Code + +If you prefer using a visual tool instead of the terminal, you can clone directly inside **Visual Studio Code**: + +1. Open VS Code. +2. Press `Ctrl + Shift + P` (or `Cmd + Shift + P` on Mac). +3. Type **Git: Clone** and press Enter. +4. Paste the GitHub URL and choose a folder on your computer. VS Code will handle the cloning process for you! + +## Important Note for Beginners + +**Only clone once.** A common mistake is running `git clone` every time you want to work on a project. + + * Use `git clone` the **first time** you get the project. + * Use `git pull` every time **after that** to get the latest updates. + +:::tip +By default, Git clones the project into a folder named after the repository. If you want to name the folder something else, just add the name at the end: +`git clone https://github.com/user/repo.git my-custom-folder-name` +::: \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/collaboration/fork.mdx b/absolute-beginners/git-github-beginner/collaboration/fork.mdx new file mode 100644 index 0000000..5d26456 --- /dev/null +++ b/absolute-beginners/git-github-beginner/collaboration/fork.mdx @@ -0,0 +1,72 @@ +--- +title: "Forking a Repository" +sidebar_label: "1. Forking" +sidebar_position: 1 +description: "Learn how to create your own personal copy of an existing project on GitHub to experiment and contribute. This is the essential first step in your journey to becoming a proficient GitHub user and open-source contributor." +tags: ["git", "github", "forking", "open-source", "contributing"] +keywords: ["git", "github", "forking", "open-source", "contributing"] +--- + +In the world of Open Source, you often find amazing projects that you want to improve or use as a starting point for your own work. However, you don't have permission to edit the original code directly. + +This is where **Forking** comes in. At **CodeHarborHub**, we consider forking the first step toward becoming a true Open Source contributor. + +:::info +If you are new to GitHub, forking is the best way to get your own copy of a project that you can experiment with and eventually contribute back to the original author. +::: + +## What is a Fork? + +A **Fork** is a complete copy of a repository that is managed under **your** GitHub account instead of the original author's. It allows you to freely make changes without affecting the original project. You can then propose your changes to the original author through a **Pull Request**. + +### The "Notebook" Analogy + +Imagine your teacher has a master notebook with a great science experiment. +* You can't write in the teacher's notebook. +* You **Fork** it by taking the notebook to a photocopier. +* Now you have your own copy. you can change the steps, add drawings, or fix typos without changing the teacher's master version. + +## How to Fork a Project + +Forking is a "one-click" process that happens entirely on the GitHub website. + +1. **Find the Project:** Navigate to the repository you want to fork (e.g., `github.com/codeharborhub/git-tutorial`). +2. **Locate the Button:** In the top-right corner of the page, click the **Fork** button. +3. **Configure (Optional):** GitHub will ask if you want to copy just the `main` branch or all branches. For beginners, "main branch only" is usually best. +4. **Create:** Click **Create Fork**. + +## Why do we Fork? (Use Cases) + +| Use Case | Description | +| :--- | :--- | +| **Contributing** | You found a bug in a project and want to fix it. You fork the repo, fix the bug in your copy, and then ask the owner to pull your fix. | +| **Experimentation** | You want to try a new feature but don't want to break the original project's stable code. | +| **Starting Point** | You found a "Boilerplate" or "Template" project that you want to use as the foundation for your own new app. | + +## Forking vs. Cloning + +It is very common for beginners to confuse these two. Here is the professional breakdown: + +```mermaid +graph TD + A[Original Project] -- "Fork (Cloud)" --> B[Your GitHub Fork] + B -- "Clone (Local)" --> C[Your Computer] + C -- "Commit & Push" --> B +``` + + * **Forking** happens on the **GitHub Server**. It creates a copy on the cloud. + * **Cloning** happens on **Your Machine**. It downloads the code so you can work offline. + +## Keeping Your Fork Up-to-Date + +One challenge with forking is that the original project keeps moving forward. If the original author adds a new feature, your fork won't have it automatically. + +To sync your fork, you can use the **Sync Fork** button on the GitHub interface of your repository: + +1. Go to your forked repo on GitHub. +2. Click **Sync fork**. +3. Click **Update branch**. + +:::tip +Forking is a "Public" action. Everyone can see that you forked a project, and it often shows up on your profile as a sign that you are active in the developer community! +::: \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/collaboration/index.mdx b/absolute-beginners/git-github-beginner/collaboration/index.mdx deleted file mode 100644 index e345ed2..0000000 --- a/absolute-beginners/git-github-beginner/collaboration/index.mdx +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/collaboration/oss-licenses.mdx b/absolute-beginners/git-github-beginner/collaboration/oss-licenses.mdx new file mode 100644 index 0000000..433aa19 --- /dev/null +++ b/absolute-beginners/git-github-beginner/collaboration/oss-licenses.mdx @@ -0,0 +1,71 @@ +--- +title: "Open Source Licenses" +sidebar_label: "7. OSS Licenses" +sidebar_position: 7 +description: "Understand the legal side of Open Source and learn how to choose the right license for your projects. This is crucial for protecting your work and allowing others to use and contribute to it. Master the art of licensing to ensure your code can be shared and built upon by the community while safeguarding your rights as a creator." +tags: ["git", "github", "open source licenses", "collaboration", "legal", "protection", "sharing"] +keywords: ["git", "github", "open source licenses", "collaboration", "legal", "protection", "sharing"] +--- + +Making a repository "Public" on GitHub does not automatically mean people can use, modify, or share your code. Without a **License**, your code is technically under "Exclusive Copyright," meaning you own it and no one else can touch it. + +At **CodeHarborHub**, we believe in sharing. A license is a simple text file that tells the community exactly what they are allowed to do with your work. + +:::info +Think of a license like the "Terms and Conditions" for your code. It sets the rules for how others can use, modify, and share your project. Without it, your code is like a locked treasure chest that no one can open. +::: + +## Why Do You Need a License? + +1. **Permission:** It legally allows others to "Fork" and "Clone" your project. +2. **Protection:** Most licenses include a "No Warranty" clause, meaning you aren't responsible if your code breaks someone else's computer. +3. **Contribution:** Professional developers and companies will *never* use or contribute to a project that doesn't have a clear license. + +## The "Big Three" Licenses + +There are hundreds of licenses, but in the professional world, 90% of projects use one of these three: + +| License | Type | Permission Level | Summary | +| :--- | :--- | :--- | :--- | +| **MIT** | **Permissive** | High | "Do whatever you want, just keep my name on it." | +| **Apache 2.0** | **Permissive** | High | Similar to MIT, but gives extra protection against patent lawsuits. | +| **GNU GPLv3** | **Copyleft** | Medium | "You can use my code, but your project MUST also be open source." | + +## Which One Should You Choose? + +### 1. The MIT License (Recommended for Beginners) +This is the most popular license at **CodeHarborHub**. It is short, simple, and very "friendly." It allows people to use your code in private, commercial, and open-source projects. +* **Use it if:** You want the most people possible to use your code. + +### 2. The Apache License 2.0 +This is the standard for large-scale professional projects (like Android or Kubernetes). +* **Use it if:** You are building a serious library or tool and want to be professional about patents. + +### 3. The GNU GPLv3 +This is a "Restrictive" or "Copyleft" license. If someone uses your GPL code, they are legally forced to make their entire project open source too. +* **Use it if:** You want to ensure that no one ever takes your code and makes a "secret" paid version of it. + +## How to Add a License to Your Repo + +GitHub makes this incredibly easy. You don't need a lawyer! + +1. Go to your repository on GitHub. +2. Click **Add file** > **Create new file**. +3. Type `LICENSE` (all caps) as the filename. +4. A button will appear: **"Choose a license template"**. Click it. +5. Select a license (like MIT), click **Review and submit**, and commit the file. + +## What Happens if I Don't Choose One? + +If you have a public repo with **no license**: +* People can read your code. +* People can fork your code (because GitHub's Terms of Service allow it). +* **But**, people cannot legally use your code in their own apps, and they cannot contribute back to you safely. + +> **Moral of the story:** If you want people to use your work, always add an **MIT License**. + +:::tip +Not sure which one fits your specific vibe? Check out [choosealicense.com](https://choosealicense.com/). It's a simple tool created by GitHub to help you pick the perfect legal protection for your code. +::: + +Now that you understand the legal side of sharing your code, you're ready to make your projects truly open source. In the next chapter, we'll dive into how to keep your fork in sync with the original project using the concept of "Upstream." This is essential for contributing to open-source projects and ensuring your code is built on the most recent version of the project. Let's get started!s \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/collaboration/pull-and-push.mdx b/absolute-beginners/git-github-beginner/collaboration/pull-and-push.mdx new file mode 100644 index 0000000..e1f300f --- /dev/null +++ b/absolute-beginners/git-github-beginner/collaboration/pull-and-push.mdx @@ -0,0 +1,80 @@ +--- +title: "Pulling and Pushing Changes" +sidebar_label: "4. Pull & Push" +sidebar_position: 4 +description: "Learn the daily workflow of syncing your local code with GitHub to keep your project up-to-date. Master the essential commands for pulling changes from the remote repository and pushing your work to share with your team. This is a crucial skill for collaborating effectively in any software development project." +tags: ["git", "github", "pull", "push", "syncing", "collaboration"] +keywords: ["git", "github", "pull", "push", "syncing", "collaboration"] +--- + +In a collaborative environment like **CodeHarborHub**, code is constantly moving between your computer (Local) and GitHub (Remote). To stay in sync with your team, you must master the two most frequent actions in a developer's day: **Pulling** and **Pushing**. + +:::important +Pulling and Pushing are the heartbeat of any project. They keep everyone on the same page and ensure that your work is shared with the world. Master these commands to become a true collaborator at **CodeHarborHub**. +::: + +## The "Daily Cycle" Concept + +Think of a shared **Google Doc**. +* **Pulling** is like refreshing the page to see what your friends wrote while you were away. +* **Pushing** is like hitting "Save" so your friends can see what *you* just wrote. + +## 1. Pulling Changes (`git pull`) + +**When to use it:** Every morning before you start coding, and every time a teammate tells you they've finished a feature. + +When you run `git pull`, two things happen: +1. Git **Fetches** the new data from GitHub. +2. Git **Merges** that data into your local files. + +```bash +# Get the latest code from the 'main' branch on GitHub +git pull origin main +``` + +## 2. Pushing Changes (`git push`) + +**When to use it:** After you have "Staged" and "Committed" your work locally and you are ready to share it with the world. + +```bash +# Send your 'feat-login' branch to GitHub +git push origin feat-login +``` + +## The "Golden Workflow" + +At an **Industrial Level**, we follow this 4-step loop to avoid errors and conflicts: + +| Step | Command | Why? | +| :--- | :--- | :--- | +| **1. Update** | `git pull origin main` | Start with the latest version of the project. | +| **2. Code** | *(Work in VS Code)* | Make your magic happen. | +| **3. Save** | `git add .` & `git commit` | Create your local "Save Point." | +| **4. Share** | `git push origin your-branch` | Upload your work to the cloud. | + +## Dealing with "Rejected" Pushes + +Sometimes, you try to `git push` and see a scary red error message: **[rejected]**. + +**Why did this happen?** +This happens because a teammate pushed code to GitHub *after* your last pull. GitHub won't let you push your work because it would overwrite your teammate's work. + +**The Fix:** + +1. **Pull first:** `git pull origin main` +2. **Resolve any conflicts** (if they exist). +3. **Push again:** `git push origin main` + +## The `fetch` Alternative + +If you want to see what your teammates did **without** merging it into your files yet, use: + +```bash +git fetch origin +``` + +This downloads the data but doesn't change your code. It's like "Previewing" the changes before you commit to them. + +:::tip +Always **Pull before you Push**. This simple habit will save you from 90% of the merge conflicts you might face at **CodeHarborHub**. +::: \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/collaboration/pull-requests.mdx b/absolute-beginners/git-github-beginner/collaboration/pull-requests.mdx new file mode 100644 index 0000000..706b2e6 --- /dev/null +++ b/absolute-beginners/git-github-beginner/collaboration/pull-requests.mdx @@ -0,0 +1,82 @@ +--- +title: "Creating a Pull Request (PR)" +sidebar_label: "3. Pull Requests" +sidebar_position: 3 +description: "Learn how to propose your changes to a project by creating a Pull Request (PR) on GitHub. This is the essential step for contributing your work to an open-source project and collaborating with other developers. Master the PR process to share your improvements and get feedback from the community." +tags: ["git", "github", "pull request", "code review", "open-source", "contributing"] +keywords: ["git", "github", "pull request", "code review", "open-source", "contributing"] +--- + +A **Pull Request** is the bridge between your personal work and a shared project. It is a formal way to tell a project maintainer: *"I have finished a feature or a bug fix. Please review my code and 'pull' it into the main project."* + +At **CodeHarborHub**, PRs are where we learn from each other through code reviews and discussion. + +:::info +If you are new to GitHub, creating a Pull Request is the best way to share your work with others and contribute to open-source projects. It allows you to get feedback and have your code reviewed by experienced developers. +::: + +## The "Job Interview" Analogy + +Think of a Pull Request like **Applying for a Job**: +1. **The Resume (Commits):** You prepare your best work on your own time (your branch). +2. **The Application (The PR):** You submit your work to the company (the original repo). +3. **The Interview (Code Review):** The team looks at your work, asks questions, and might suggest improvements. +4. **The Hire (Merge):** Your code is accepted and becomes part of the official project! + +## Step-by-Step: Opening a PR + +### 1. Push Your Branch + +Before you can open a PR, you need to push your changes to GitHub. Make sure you are on the correct branch and run: + +```bash +git push origin feat-new-feature +``` + +### 2. Start the Request + +Go to the original repository on GitHub (not your fork). You should see a banner that says: "Your recently pushed branches: feat-new-feature". Click the green **Compare & pull request** button. If you don't see the banner, you can also click the **Pull Requests** tab and then click **New Pull Request**. + +### 3. Fill Out the Details + +This is the most important part of a professional PR. A good PR includes: + + * **A Clear Title:** `feat: add user profile picture upload` + * **The "Why":** Explain what problem this code solves. + * **The "How":** Briefly mention the technical changes you made. + * **Screenshots:** If you changed the UI, add a "Before" and "After" image. + +## The Lifecycle of a PR + +```mermaid +graph TD + A[Open PR] --> B{Review} + B -->|Changes Requested| C[You Update Your Code] + C --> B + B -->|Approved| D[Maintainer Merges PR] + D --> E[Feature is Live!] +``` + +## PR Etiquette for CodeHarborHub + +To get your PR merged quickly, follow these "Industrial-Level" rules: + +| Rule | Description | +| :--- | :--- | +| **Keep it Small** | It is easier to review 10 small PRs than 1 giant PR that changes 50 files. | +| **Test Your Code** | Make sure your code actually runs and doesn't break existing features before submitting. | +| **Be Polite** | Code review is a conversation. Be open to feedback and explain your choices calmly. | +| **Link Issues** | If your PR fixes a bug, write `Closes #12` in the description. GitHub will automatically close the bug report when the PR is merged. | + +## Updating an Open PR + +If a reviewer asks you to change something, you **don't** need to open a new PR. + +1. Make the changes on your computer. +2. `git add` and `git commit` them. +3. `git push` to the same branch. +4. The PR on GitHub will **automatically update** with your new changes\! + +:::tip +A **Draft Pull Request** is a great way to show people what you are working on before it's finished. It tells the team: "I'm working on this, but don't merge it yet!" +::: \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/collaboration/resolving-conflicts.mdx b/absolute-beginners/git-github-beginner/collaboration/resolving-conflicts.mdx new file mode 100644 index 0000000..36f6b67 --- /dev/null +++ b/absolute-beginners/git-github-beginner/collaboration/resolving-conflicts.mdx @@ -0,0 +1,104 @@ +--- +title: "Resolving Merge Conflicts" +sidebar_label: "6. Merge Conflicts" +sidebar_position: 6 +description: "Learn how to handle and fix code collisions when multiple people edit the same file. This is a crucial skill for any developer working in a team. Master the art of resolving merge conflicts to keep your project running smoothly and maintain a harmonious codebase." +tags: ["git", "github", "merge conflicts", "collaboration", "version control", "teamwork"] +keywords: ["git", "github", "merge conflicts", "collaboration", "version control", "teamwork"] +--- + +In a collaborative community like **CodeHarborHub**, a **Merge Conflict** is a common rite of passage. It happens when Git is unsure how to combine two different sets of changes. + +Instead of guessing and potentially breaking your code, Git stops and says: *"I need a human to decide which version is correct."* + +:::danger +Merge conflicts can be intimidating at first, but they are a normal part of working with Git. With practice, you'll become a pro at resolving them quickly and confidently. Don't let the red flags scare you! +::: + +## Why do Conflicts happen? + +A conflict occurs when: +1. Two people edit the **same line** of the same file on different branches. +2. One person deletes a file that another person is currently editing. + +When you try to merge or pull, Git doesn't know which version to keep, so it throws up a red flag and asks for your help. + +## Identifying a Conflict + +When you run `git merge` or `git pull`, and a conflict exists, your terminal will look like this: + +```bash +Auto-merging index.html +CONFLICT (content): Merge conflict in index.html +Automatic merge failed; fix conflicts and then commit the result. +``` + +If you open the file, Git will have inserted **Conflict Markers** to show you the "Battle Zone": + +```html title="index.html" +<<<<<<< HEAD +

Welcome to CodeHarborHub

+======= +

Welcome to our Open Source Community

+>>>>>>> feat-rebranding +``` + + * **`<<<<<<< HEAD`**: This is your current version. + * **`=======`**: The divider between the two versions. + * **`>>>>>>> branch-name`**: The version you are trying to pull in. + +## The Professional Resolution Workflow + +At **CodeHarborHub**, we use **Visual Studio Code** because it makes resolving conflicts as easy as clicking a button. + +### Step 1: Open the Conflicted File + +In VS Code, the file name will turn **Red**, and the conflict area will be highlighted in blue and green. + +### Step 2: Choose Your Version + +Above the markers, VS Code gives you four "Magic Buttons": + +1. **Accept Current Change:** Keep your version, delete theirs. +2. **Accept Incoming Change:** Delete your version, keep theirs. +3. **Accept Both Changes:** Keep both (one after the other). +4. **Compare Changes:** See them side-by-side to decide. + +### Step 3: Finalize the Merge + +Once you have chosen the correct code and deleted the `<<<<`, `====`, and `>>>>` markers: + +1. **Save** the file. +2. **Stage** the fix: + ```bash + git add index.html + ``` +3. **Commit** the resolution: + ```bash + git commit -m "fix: resolve merge conflict in index.html" + ``` + +## Conflict Logic Flow + +```mermaid +graph TD + A[Start Merge] --> B{Conflict Found?} + B -- No --> C[Merge Success!] + B -- Yes --> D[Git Pauses Merge] + D --> E[Human Edits File] + E --> F[git add & git commit] + F --> G[Merge Complete] +``` + +## Tips to Avoid Conflicts + +While you can't avoid them forever, you can minimize them by following these **CodeHarborHub** standards: + + * **Pull Frequently:** Running `git pull` every hour ensures you are always working on the latest version of the code. + * **Small Commits:** If you only change 2 lines, conflicts are easy to fix. If you change 200 lines, conflicts become a nightmare. + * **Communicate:** If you are working on a specific file (like `App.js`), tell your team in Discord or Slack so they don't edit it at the same time. + +:::danger Don't Panic! +If a conflict feels too overwhelming and you want to start over, you can always "Abuse the Escape Hatch" to return everything to normal: +`git merge --abort` +::: \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/collaboration/sync-and-upstream.mdx b/absolute-beginners/git-github-beginner/collaboration/sync-and-upstream.mdx new file mode 100644 index 0000000..132cdfb --- /dev/null +++ b/absolute-beginners/git-github-beginner/collaboration/sync-and-upstream.mdx @@ -0,0 +1,102 @@ +--- +title: "Syncing Your Fork (The Upstream)" +sidebar_label: "5. Syncing & Upstream" +sidebar_position: 5 +description: "Learn how to connect to the original repository to keep your personal fork updated with the latest changes. This is essential for contributing to open-source projects and ensuring your code is built on the most recent version of the project. Master the concept of 'upstream' to stay in sync with the main project and avoid merge conflicts." +tags: ["git", "github", "forking", "syncing", "upstream", "open-source", "contributing"] +keywords: ["git", "github", "forking", "syncing", "upstream", "open-source", "contributing"] +--- + +When you **Fork** a project like a CodeHarborHub repository, you create a "Snapshot" of that project at that exact moment. However, the original project keeps growing. New features are added, and bugs are fixed every day. + +To keep your copy from becoming outdated, you need to link it back to the "Source of Truth." In Git, we call this source the **Upstream**. + +:::info +The Upstream is the original repository you forked from. It is the "Source of Truth" that your forked copy should stay in sync with. By connecting to the upstream, you can pull in the latest changes and ensure your work is built on the most recent version of the project. +::: + +## Understanding the Two Remotes + +Once you've forked and cloned, your project has two "Cloud" versions it can talk to: + +1. **Origin:** This is **your** fork on GitHub. You have permission to push code here. +2. **Upstream:** This is the **original** project (e.g., CodeHarborHub). You can only pull code from here. + +```mermaid +graph TD + A[Your Local PC] -->|git push| B[Your GitHub Fork (Origin)] + B -->|Pull Request| C[Original Repo (Upstream)] + C -->|git pull| A +``` + +## Step 1: Setting the Upstream + +By default, your clone only knows about `origin`. You need to manually tell it where the `upstream` is. You only do this **once** per project. + +1. Go to the **original** repository on GitHub (not your fork). +2. Copy the URL. +3. Run the following command in your terminal: + +```bash +git remote add upstream https://github.com/codeharborhub/original-project.git +``` + +**Verify your connection:** + +```bash +git remote -v +``` + +*You should see both `origin` and `upstream` in the list.* + +## Step 2: Syncing Your Code + +Whenever you want to bring the latest changes from the original project into your local machine, follow this professional workflow: + +### The "Pull from Upstream" Method + +```bash +# 1. Switch to your main branch +git checkout main + +# 2. Pull the latest code from the original source +git pull upstream main + +# 3. Update your GitHub fork (the origin) so they match +git push origin main +``` + +## The Sync Workflow + +```mermaid +graph TD + A[CodeHarborHub (Upstream)] -->|git pull upstream| B[Your Local PC] + B -->|git push origin| C[Your GitHub Fork (Origin)] + + subgraph "Syncing Process" + B + end +``` + +## Why is this important? + +| Problem | The Upstream Solution | +| :--- | :--- | +| **Old Code** | You are writing code for a version of the app that is 2 months old. | +| **Merge Conflicts** | When you finally open a Pull Request, your code clashes with 50 other changes made by the team. | +| **Bugs** | You are trying to fix a bug that the main team already fixed last week. | +| **Wasted Time** | You spend hours debugging an issue that was already resolved in the latest version. | + +## The GitHub "Easy Way" (Sync Fork Button) + +GitHub now provides a button on your repository page called **"Sync Fork"**. + +1. Click **Sync Fork**. +2. Click **Update Branch**. +3. Then, run `git pull origin main` on your computer to bring those changes down. + +**Note:** While the button is easy, professional engineers prefer the `upstream` terminal method because it gives them more control during complex merges. + +:::tip +Always sync your fork **before** you start working on a new feature. This ensures you are building on the most recent, stable foundation provided by the **CodeHarborHub** team. +::: \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/more-git/_category_.json b/absolute-beginners/git-github-beginner/more-git/_category_.json new file mode 100644 index 0000000..a24fec8 --- /dev/null +++ b/absolute-beginners/git-github-beginner/more-git/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "More Git", + "position": 6, + "link": { + "type": "generated-index", + "title": "More Git Guides for Absolute Beginners", + "description": "Ready to level up your Git skills? This section dives into more advanced topics like resolving merge conflicts and choosing the right open source license for your projects. Whether you're collaborating with a team or sharing your code with the world, these guides will help you navigate the complexities of Git and GitHub with confidence. Let's go beyond the basics and master the tools that power modern software development!" + } +} \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/more-git/cherry-picking.mdx b/absolute-beginners/git-github-beginner/more-git/cherry-picking.mdx new file mode 100644 index 0000000..22bcefe --- /dev/null +++ b/absolute-beginners/git-github-beginner/more-git/cherry-picking.mdx @@ -0,0 +1,84 @@ +--- +title: "Cherry Picking Commits" +sidebar_label: "4. Cherry Picking" +sidebar_position: 4 +description: "Learn how to select and apply specific commits from one branch to another without merging the entire branch. Perfect for hotfixes and selective updates." +tags: ["git", "cherry picking", "selective commits", "hotfixes", "code management"] +keywords: ["git cherry-pick", "selective commits", "hotfixes", "code management", "commit ID", "conflicts"] +--- + +In the standard Git workflow, we usually combine branches using **Merge** or **Rebase**. However, sometimes you don't want the whole branch—you just want one specific "Win." + +**Cherry Picking** allows you to pick a single commit from any branch in your repository and apply it to your current branch. + +:::warning A Note on Terminology +The term "Cherry Picking" is a bit whimsical, but it perfectly captures the idea of selecting just one "cherry" (commit) from a "bunch" (branch) without taking the whole thing. +::: + +## The "Grocery Store" Analogy + +Imagine you are at a grocery store. +* **Merging** is like buying the entire pre-packaged "Fruit Basket." You get the apples, the grapes, and the bananas, even if you only wanted the grapes. +* **Cherry Picking** is like walking up to the fruit stand, picking one perfect apple, and putting it in your own basket. You leave the rest of the fruit behind. + +## When to use Cherry Picking? + +At **CodeHarborHub**, we use cherry-picking in these specific "Industrial" scenarios: + +1. **Hotfixes:** You fixed a critical bug in a `testing` branch, and you need that exact fix in the `main` branch **now**, without pulling in all the other unfinished test code. +2. **Undo a Revert:** If you accidentally reverted a commit, you can cherry-pick the original commit back into your history. +3. **Collaborative "Theft":** Your teammate wrote a perfect `Button.js` component on their messy `experimental-ui` branch. You can cherry-pick just that component commit into your clean branch. + +## Step-by-Step: How to Cherry Pick + +### 1. Find the Commit ID +First, you need the "ID" (the SHA hash) of the commit you want to steal. You can find this on GitHub or by using: + +```bash +git log --oneline --all +``` + +*Look for the 7-character code (like `a1b2c3d`) next to the commit message.* + +### 2. Switch to the Destination + +Move to the branch where you want the commit to land: + +```bash +git checkout main +``` + +### 3. Pick the Cherry + +Run the command followed by the commit ID: + +```bash +git cherry-pick a1b2c3d +``` + +## Merge vs. Cherry Pick + +| Feature | Git Merge | Git Cherry Pick | +| :--- | :--- | :--- | +| **Scope** | Combines the **entire** branch history. | Copies **one specific** commit. | +| **History** | Creates a "Merge Commit." | Creates a brand new commit on your branch. | +| **Use Case** | Finishing a feature. | Porting a specific fix or component. | + +## Handling Cherry-Pick Conflicts + +Just like a merge, if the "Cherry" you are picking changes the same lines as your current branch, a conflict will occur. + +**The Fix:** + +1. Open the file in **VS Code**. +2. Resolve the conflict as usual. +3. Run: + + ```bash + git add . + git cherry-pick --continue + ``` + +:::warning A Note on Duplicate History +When you cherry-pick, you are creating a **copy** of a commit. If you later merge the original branch into your current branch, Git is usually smart enough to know they are the same, but it can sometimes lead to a "messy" history. Use cherry-picking sparingly\! +::: \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/more-git/git-hooks.mdx b/absolute-beginners/git-github-beginner/more-git/git-hooks.mdx new file mode 100644 index 0000000..55d38b4 --- /dev/null +++ b/absolute-beginners/git-github-beginner/more-git/git-hooks.mdx @@ -0,0 +1,65 @@ +--- +title: Automating with Git Hooks +sidebar_label: 5. Git Hooks +sidebar_position: 5 +description: Learn how to use Git Hooks to automate tasks like linting, testing, and formatting before you commit or push. +--- + +In a professional environment like **CodeHarborHub**, we want to ensure that the code we share is always high quality. We don't want to manually check for typos, formatting errors, or broken tests every single time. + +**Git Hooks** are scripts that Git executes automatically when specific actions happen—like committing, pushing, or receiving code. + +## What are Git Hooks? + +Think of a Git Hook as a **Security Guard** standing at the entrance of your repository. +* When you try to `commit`, the guard checks if you formatted your code correctly. +* When you try to `push`, the guard checks if all your tests pass. +* If the guard finds an error, they block the action until you fix it. + +## The Two Types of Hooks + +| Type | Location | Use Case | +| :--- | :--- | :--- | +| **Client-Side** | Your PC | Checks code style (Linting), runs local tests, checks commit messages. | +| **Server-Side** | GitHub/Cloud | Enforces branch permissions, triggers "Deployment" to a website. | + +## Common Hooks at CodeHarborHub + +### 1. Pre-commit Hook +This runs **before** you are even allowed to create a commit. +* **The Goal:** Catch small mistakes early. +* **Example:** It can automatically run `Prettier` to fix your code formatting so you don't have to think about it. + +### 2. Pre-push Hook +This runs **before** your code is sent to GitHub. +* **The Goal:** Prevent "Breaking the Build." +* **Example:** It runs your entire test suite. If a single test fails, the push is cancelled, preventing you from sending broken code to your teammates. + +## Where are Hooks stored? + +Every Git project has a hidden folder called `.git/hooks`. If you look inside, you will see several sample files (like `pre-commit.sample`). To activate a hook, you simply remove the `.sample` extension and add your script. + +## Modern Tooling: Husky + +Writing raw shell scripts for hooks can be difficult. At **CodeHarborHub**, we recommend using a tool called **Husky** (for JavaScript/Node projects). It makes managing hooks as easy as editing your `package.json`. + +```bash +# Example: Adding a pre-commit hook with Husky +npx husky add .husky/pre-commit "npm test" +``` + +*Now, every time you run `git commit`, your tests will run automatically\!* + +## Industrial Best Practices + +1. **Don't Overdo It:** If your hooks take 10 minutes to run, you will start hating the `commit` command. Keep hooks fast! +2. **Shared Hooks:** Ensure your team uses the same hooks so everyone follows the same code style. +3. **The "Emergency Escape":** If you absolutely MUST commit something and skip the hooks (e.g., a tiny typo fix in a README), you can use the "no-verify" flag: + + ```bash + git commit -m "fix: tiny typo" --no-verify + ``` + +:::tip +Git Hooks are stored locally in the `.git` folder, which is **not** pushed to GitHub. To share hooks with your team, use a tool like **Husky** or **pre-commit (Python)** which stores the configuration in your project files\! +::: \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/more-git/index.mdx b/absolute-beginners/git-github-beginner/more-git/index.mdx deleted file mode 100644 index e345ed2..0000000 --- a/absolute-beginners/git-github-beginner/more-git/index.mdx +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/more-git/rebase-merge-squash.mdx b/absolute-beginners/git-github-beginner/more-git/rebase-merge-squash.mdx new file mode 100644 index 0000000..7a14f68 --- /dev/null +++ b/absolute-beginners/git-github-beginner/more-git/rebase-merge-squash.mdx @@ -0,0 +1,120 @@ +--- +title: "Rebase, Merge, and Squash" +sidebar_label: "2. Rebase, Merge & Squash" +sidebar_position: 2 +description: "Learn the three different ways to combine your work and how they affect your project's history. Understand the pros and cons of each method and when to use them in a professional development environment." +tags: ["git", "merge", "rebase", "squash", "version control", "collaboration"] +keywords: ["git merge", "git rebase", "git squash", "version control", "collaboration", "git history"] +--- + +In a team environment, you often work on a **Feature Branch** while the **Main Branch** continues to receive updates from other developers. Eventually, you need to bring your code into the main project. + +There are three professional ways to do this, and each one tells a different "story" in your Git history. + +:::info +The "Main Branch" is often called `main` or `master`, and the "Feature Branch" is whatever you named it (e.g., `feat-new-ui`). +::: + +## 1. Git Merge (The Standard) +**Merge** takes the entire history of your feature branch and ties it together with the main branch using a "Merge Commit." + +* **The Story:** "I worked on this feature over 3 days, and here is exactly when I finished it." +* **Best For:** Preserving a complete, chronological record of every action. + +```mermaid +gitGraph + commit id: "Initial" + branch feature + checkout main + commit id: "Main Work" + checkout feature + commit id: "Feature Work" + checkout main + merge feature id: "Merge Commit" +``` + +## 2. Git Rebase (The Clean Path) + +**Rebase** takes your commits and "moves" them so they start from the very latest commit on the main branch. It effectively rewrites history to make it look like you started your work today. + + * **The Story:** "My work happened in a perfect, straight line." + * **Best For:** Keeping a clean, easy-to-read history without "Merge Commits" cluttering the log. + +```mermaid +gitGraph + commit id: "Initial" + commit id: "Main Work" + branch feature + checkout feature + commit id: "Feature Work" + checkout main + merge feature +``` + +*(Note: In the diagram, the 'Feature Work' appears as if it happened directly after 'Main Work'.)* + +## 3. Git Squash (The Summary) + +**Squash** takes all the tiny commits in your feature branch (e.g., "fixed typo", "added button", "fixed typo again") and crushes them into **one single, clean commit** before merging. + + * **The Story:** "I added this entire feature in one solid move." + * **Best For:** Cleaning up "messy" development branches before they hit the professional production code. + +```mermaid +graph LR + subgraph "Feature Branch" + C1[Fix typo] --> C2[Add UI] + C2 --> C3[Final touch] + end + C3 -- "SQUASH" --> S1[Feat: Add New UI] + S1 --> Main[Main Branch] +``` + +## Comparison Table + +| Feature | Merge | Rebase | Squash | +| :--- | :--- | :--- | :--- | +| **History Style** | Branching / Nonlinear | Linear (Straight line) | Simplified (One commit) | +| **Traceability** | High (Shows every move) | Medium (Clean but edited) | Low (Individual steps lost) | +| **Difficulty** | Easy | Advanced (Can be tricky) | Easy | +| **Usage** | Shared branches | Local/Feature branches | Pull Requests | + +## How to execute them + + + + +If you want to merge your feature branch into main, you would do: + +```bash +git checkout main +git merge feat-new-ui +``` + + + + +If you want to rebase your feature branch onto the latest main, you would do: + +```bash +# While on your feature branch +git rebase main +``` + + + + +Usually done via GitHub during a Pull Request. You select **"Squash and merge"** from the green button dropdown. + + + + +## Industrial Best Practices at CodeHarborHub + +1. **Rebase Locally:** Rebase your feature branch against `main` before opening a Pull Request. This ensures your code is up-to-date and the history is clean. +2. **Squash on Merge:** When a team lead merges your PR, they will often "Squash" it so the main history only shows "Feat: Add User Dashboard" instead of 50 tiny commits. +3. **Never Rebase Public Branches:** Do not rebase a branch that other people are already working on. It will break their local history! + +:::tip +If you get stuck during a complex rebase and everything feels broken, don't panic. You can always run `git rebase --abort` to return to the way things were before you started. +::: \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/more-git/reset-and-revert.mdx b/absolute-beginners/git-github-beginner/more-git/reset-and-revert.mdx new file mode 100644 index 0000000..e7bd13e --- /dev/null +++ b/absolute-beginners/git-github-beginner/more-git/reset-and-revert.mdx @@ -0,0 +1,88 @@ +--- +title: "Reset vs. Revert" +sidebar_label: "1. Reset & Revert" +sidebar_position: 1 +description: "Learn the crucial difference between 'Reset' and 'Revert' in Git. This guide will teach you when to use each command to safely undo changes without losing your work. Master these tools to confidently fix mistakes and maintain a clean project history." +tags: ["git", "github", "reset", "revert", "undo", "version control", "history management"] +keywords: ["git", "github", "reset", "revert", "undo", "version control", "history management"] +--- + +Mistakes are a natural part of coding. Whether you accidentally committed a bug or realized your last three hours of work were a bad idea, Git provides two main ways to go back in time. + +The secret to being a pro at **CodeHarborHub** is knowing when to use the **Eraser (Reset)** and when to use the **Correction (Revert)**. + +:::danger +Using the wrong command can lead to lost work or a messy project history. Always double-check which one you need before you hit enter! +::: + +## 1. Git Reset (The "Eraser") + +`git reset` moves your current branch pointer backward to an older commit. It’s like using an eraser on a pencil drawing—the work you erase simply disappears from the history. + +### The Three Flavors of Reset +Depending on what you want to keep, you use different flags: + +| Flag | What happens to your code? | Safety | +| :--- | :--- | :--- | +| **`--soft`** | Keeps all changes in the **Staging Area**. | Safe | +| **`--mixed`** | Keeps changes but puts them in **Working Directory**. | Neutral | +| **`--hard`** | **Deletes everything.** Changes are gone forever. | Dangerous | + +**Use Case:** Use Reset when you are working **locally** on your own branch and haven't pushed to GitHub yet. + +## 2. Git Revert (The "Correction") + +`git revert` is the professional way to undo changes on a shared project. Instead of deleting the past, it creates a **new commit** that does the exact opposite of the one you want to remove. + +**Analogy:** Imagine a bank ledger. Instead of ripping out a page (Reset), the bank adds a new line that says "Refund: -$50" to cancel out an error. + +**Use Case:** Use Revert for **Public Branches** (like `main`) where other team members are also working. + +## Comparison: Which one should I use? + +| Feature | Git Reset | Git Revert | +| :--- | :--- | :--- | +| **History** | Deletes/Rewrites history. | Preserves history (adds a new entry). | +| **Best Environment**| Local / Private branches. | Public / Shared branches. | +| **Risk** | High (can lose uncommitted code). | Low (nothing is ever deleted). | +| **Result** | Cleaner history, but dangerous. | Messier history, but much safer. | + +## Practical Examples + + + + +If you just committed a file with a typo and want to fix it: + +```bash +# Move back 1 commit but keep your code staged +git reset --soft HEAD~1 +# Fix the typo in VS Code, then: +git add . +git commit -m "feat: correct typo and add logic" +``` + + + + +If you pushed code to the `main` branch that is crashing the live site: + +```bash +# Find the ID of the bad commit using git log +git revert a1b2c3d +# This creates a 'reversal commit'. Now push it: +git push origin main +``` + + + + +## The Golden Rule of Undoing + +> **"Never Reset what you have Pushed."** + +If you use `git reset` on code that is already on GitHub, and then try to push, your teammates' computers will get confused because the history "disappeared." At **CodeHarborHub**, we always use `revert` for anything that has already been shared with the team. + +:::danger Warning +`git reset --hard` is the only command in Git that can truly destroy your work. Always run `git status` or `git stash` before using it to make sure you don't have unsaved progress\! +::: \ No newline at end of file diff --git a/absolute-beginners/git-github-beginner/more-git/stashing.mdx b/absolute-beginners/git-github-beginner/more-git/stashing.mdx new file mode 100644 index 0000000..e08df92 --- /dev/null +++ b/absolute-beginners/git-github-beginner/more-git/stashing.mdx @@ -0,0 +1,95 @@ +--- +title: "Stashing Your Work" +sidebar_label: "3. Stashing" +sidebar_position: 3 +description: "Learn how to temporarily shelf your changes without committing them using Git Stash. Perfect for when you need to switch tasks quickly without losing your progress." +tags: ["git", "stashing", "temporary storage", "context switching", "code management"] +keywords: ["git stash", "temporary storage", "context switching", "code management", "unstaged changes", "staged changes"] +--- + +Imagine you are deep into coding a complex "Dark Mode" feature for **CodeHarborHub**. Your workspace is messy, and your code isn't finished. Suddenly, a critical bug is found on the live site that you need to fix **immediately**. + +You can't commit your "Dark Mode" code because it's half-finished, and Git won't let you switch branches while you have unsaved changes. + +**The solution?** Use `git stash`. + +## What is Stashing? + +`git stash` takes your uncommitted changes (both staged and unstaged) and "hides" them in a temporary storage area within Git. This gives you a **clean working directory** so you can switch tasks instantly. + +**Analogy:** It’s like being in the middle of a puzzle on your dining table. If you need the table for dinner, you don't throw the puzzle away; you slide it onto a tray and put it in a drawer. When dinner is over, you slide the tray back onto the table and continue exactly where you left off. + +## The Stashing Workflow + +### 1. Hide your work +When the interruption happens, run: + +```bash +git stash +``` + +*Your code is now safe, and your folder looks exactly like it did at your last commit.* + +### 2. Switch and Fix + +Now you can safely switch branches to fix that urgent bug: + +```bash +git checkout main +# ... fix bug, commit, and push ... +``` + +### 3. Bring your work back + +Switch back to your feature branch and retrieve your hidden work: + +```bash +git checkout feat-dark-mode +git stash pop +``` + +*The `pop` command takes the work out of the "drawer" and puts it back into your files.* + +## Managing the "Stash Stack" + +You can stash multiple times! Git keeps them in a "Stack" (the newest stash is always on top). + +| Command | Action | +| :--- | :--- | +| **`git stash list`** | See all your "hidden trays" in the drawer. | +| **`git stash apply`** | Bring work back but keep a copy in the stash (safer than pop). | +| **`git stash drop`** | Delete the most recent stash without applying it. | +| **`git stash clear`** | Empty the entire drawer (Delete all stashes). | + +## Advanced Stashing + + + + +If you have many stashes, give them names so you don't get confused: + +```bash +git stash save "UI work in progress" +``` + + + + +By default, Git Stash only saves files it already knows about. To stash **new files** you just created, use the `-u` flag: + +```bash +git stash -u +``` + + + + +## When to use Stashing at CodeHarborHub? + +1. **Context Switching:** When a teammate needs you to review their code immediately. +2. **Pulling into a Dirty Branch:** If you try to `git pull` but have local changes that conflict, stash your work, pull, and then `pop` your stash back. +3. **Experimenting:** If you want to try a crazy idea but aren't sure it will work, stash your current stable work first. + +:::tip +Before you `git stash pop`, run `git status`. It’s always best to be on the same branch you were on when you created the stash to avoid unnecessary merge conflicts\! +::: \ No newline at end of file