[Edit] Git: Merge

content/git/concepts/merge/merge.md

@@ -1,55 +1,163 @@
 ---
 Title: 'Merge'
-Description: 'Merging allows a user to apply all changes from one branch to another when the work is completed.'
+Description: 'Allows a user to apply all changes from one branch to another without losing commit history.'
 Subjects:
   - 'Bash/Shell'
   - 'Developer Tools'
 Tags:
+  - 'Bash/Shell'
   - 'Git'
   - 'GitHub'
+  - 'Version Control'
 CatalogContent:
   - 'learn-git'
   - 'learn-the-command-line'
 ---
 
-In Git, completed changes made to a [branch](https://www.codecademy.com/resources/docs/git/branch) can be merged to the `main` branch. When collaborating on a remote repository, a [pull request](https://www.codecademy.com/resources/docs/git/pull-requests) will need to be opened in order to do this. Anyone with push access to the repository can complete the merge.
+The **`git merge`** command allows a user to apply all changes from one [branch](https://www.codecademy.com/resources/docs/git/branch) to another without losing [commit](https://www.codecademy.com/resources/docs/git/commit) history. Whether it is [merging](https://www.codecademy.com/resources/docs/git/merge) a feature branch into the main branch or integrating updates from a teammate, `git merge` ensures that project changes are combined in an organized manner.
+
+## Git Merge Syntax
+
+```pseudo
+git merge <branch-name>
+```
+
+Here, `<branch-name>` is the name of the branch whose changes are to be merged into the current branch.
+
+**Common optional flags:**
+
+- `--no-ff`: Creates a merge commit even if a fast-forward merge is possible. Keeps branch history explicit.
+- `--squash`: Combines all commits from the branch being merged into a single commit. Useful for keeping history cleaner.
+- `--abort`: Aborts a merge in progress and restores the branch to its pre-merge state.
+
+## How Git Merge Works
+
+The primary goal of `git merge` is to combine the histories of two branches in a way that preserves the integrity of all changes. To understand this process better, it helps to know what Git is doing behind the scenes.
+
+### Step 1: Identifying the Branches Involved
+
+Suppose you are on the `main` branch and want to merge changes from `feature-branch` into it. Git starts by identifying:
+
+- The current branch (where you want to apply the changes) — here, `main`.
+- The branch to merge — here, `feature-branch`.
+
+### Step 2: Finding the Merge Base
+
+In the next step, Git finds the merge base. The merge base is essentially the last commit from which both branches diverged. It acts as a reference point so Git can compare what changed on each branch since then.
+
+### Step 3: Determining the Merge Strategy
+
+Git chooses a merge strategy depending on the relationship between the current branch, the branch being merged, and their histories.
+
+Strategy 1: Fast-Forward Merge
+
+If the current branch (`main`) has no new commits after the merge base, Git can just "fast-forward" the branch pointer forward to the tip of `feature-branch`.
+
+No new commit is created here, and the history remains linear.
+
+Strategy 2: 3-Way Merge
+
+If both branches have diverged — meaning commits exist on both `main` and `feature-branch` since the merge base — Git performs a 3-way merge.
+
+Git compares:
+
+- The merge base commit
+- The HEAD of the current branch
+- The HEAD of the branch being merged
+
+Using these three points, Git figures out how the changes from each branch can be combined.
+
+It then creates a new commit called a merge commit that has two parent commits representing the integration of both histories.
+
+### Step 4: Applying Changes and Updating History
+
+During the merge process, Git:
+
+- Applies changes introduced by commits on the branch being merged that don’t exist on the current branch.
+- Preserves the commits and history of both branches.
+- Updates the current branch pointer to the new commit (either fast-forward or merge commit).
+
+## Example: Using Git Merge
+
+Let’s walk through a practical example to see how `git merge` works in action.
+
+**Scenario:**
+
+You are working on a project with two branches:
+
+- `main`: The stable production branch.
+- `feature-login`: A branch where you developed a new login feature.
+
+You want to merge the `feature-login` branch into `main`. To do so, follow these steps:
+
+Step 1: Switch to the target branch (`main`)
+
+```shell
+git switch main
+```
+
+Step 2: Retrieve the latest changes from the [remote repository](https://www.codecademy.com/resources/docs/git/remotes) (`origin`) and update your local `main`
+
+```shell
+git pull origin main
+```
+
+Step 3: Merge the `feature-login` branch into `main`
+
+```shell
+git merge feature-login
+```
+
+## Merge Conflicts
+
+Sometimes, Git can’t automatically combine changes, especially when both branches modify the same lines of a file. This results in a merge conflict.
+
+To resolve:
+
+Step 1: Open the conflicting file(s) and decide how to combine changes
 
-## Git Command
+Step 2: Remove conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
 
-To merge a branch into the local `main` branch:
+Step 3: Stage the resolved file(s)
 
 ```shell
-git checkout main     # Switch to the main branch
-git merge branch_name
+git add <file>
 ```
 
-For example, the following merges a branch called `feature_test` branch to the `main` branch:
+Step 4: Commit the merge
 
 ```shell
-git checkout main
-git merge feature_test
+git commit
 ```
 
-## Merging a Pull Request on GitHub
+## Best Practices for Using Git Merge
 
-> _For information on how to open a pull request, see the [Pull Requests](https://www.codecademy.com/resources/docs/git/pull-requests) section._
+- Pull latest changes before merging to avoid outdated merges.
+- Use descriptive branch names for clarity in commit history.
+- Test your code after merging to catch any integration issues early.
+- Consider `--no-ff` to always create a merge commit for better history tracking.
 
-1. On the GitHub repository page, click the "Pull requests" tab at the top.
+## Frequently Asked Questions
 
-2. In the "Pull Requests" list, choose the pull request that you'd like to merge.
+### 1. What is a 3-way merge?
 
-3. Depending on the merge options enabled for your repository, you can:
+A 3-way merge occurs when Git uses:
 
-   - Merge all the commits into the base branch by clicking **Merge pull request**. If the **Merge pull request** option is not shown, then click the merge drop down menu and select **Create a merge commit**.
+- The latest commit of the current branch (HEAD)
+- The latest commit of the branch to be merged
+- Their common ancestor
 
-   - Squash the commits into one commit by clicking the merge drop down menu, selecting **Squash and merge** and then clicking the **Squash and merge** button.
+Git compares all three to create a new merge commit that combines the changes.
 
-   - Rebase the commits individually onto the base branch by clicking the merge drop down menu, selecting **Rebase and merge** and then clicking the **Rebase and merge** button.
+### 2. What is `git merge` vs `git pull`?
 
-4. If prompted, type a commit message, or accept the default commit message.
+- `git merge` incorporates changes from one branch into your current branch (local operation).
+- `git pull` retrieves changes from a remote and then merges them into the current branch (remote + merge in one step).
 
-5. If you have more than one email address associated with your GitHub account, click the email address drop-down menu and select the email address to use as the Git author email address. Only verified email addresses appear in this drop-down menu. If you enabled email address privacy, then `<username>@users.noreply.github.com` is the default commit author email address.
+### 3. When should I use `git merge`?
 
-6. Click **Confirm merge**, **Confirm squash and merge**, or **Confirm rebase and merge**.
+Use `git merge` when you:
 
-7. (Optional) Last but not the least, delete the feature branch. This keeps the list of branches in your repository nice and tidy.
+- Want to combine changes from a completed feature branch into the main branch.
+- Need to integrate teammate changes into your branch without overwriting your own work.
+- Prefer to keep commit history intact instead of rewriting it (as in `git rebase`).