diff --git a/docs/merging-base.md b/docs/merging-base.md index eb086ab..a42086e 100644 --- a/docs/merging-base.md +++ b/docs/merging-base.md @@ -1,91 +1,103 @@ # Merging `base` Into an Existing Repository -This guide explains how to merge the `base` repository into your existing project. This is useful for incorporating the `base` features, such as the Docker environment and GitHub Actions, into a project that has already been started. +This guide explains how to merge the `attogram/base` repository into your existing project. This is useful for incorporating the `base` features, such as the Docker environment and GitHub Actions, into a project that has already been started. -## 1. Add `base` as a Remote +There are two ways to do this: an easy method using the GitHub web interface, and an advanced method using the command line on your local machine. -First, you need to add the `base` repository as a remote to your local Git repository. This allows you to fetch its branches and history. +--- -Open your terminal, navigate to your project's root directory, and run the following command: +## Easy Method: Using GitHub Codespaces (Web-Based) -```bash -git remote add base https://github.com/attogram/base.git -``` +This method is recommended if you are not familiar with the command line or do not have Git installed on your machine. It uses GitHub Codespaces, which provides a development environment that runs in your browser. -This command adds a new remote named `base` that points to the official `base` repository. +1. **Navigate to Your Repository:** + Go to the main page of your own existing repository on GitHub. -## 2. Fetch and Merge `base` +2. **Launch a New Codespace:** + - Click the **"<> Code"** button. + - Go to the **"Codespaces"** tab. + - Click **"Create codespace on [your-branch-name]"**. This will create a new development environment and open it in a new browser tab. -Next, fetch the `base` repository's history and merge its `main` branch into your project's main branch. +3. **Open the Terminal:** + Once the Codespace has loaded, you will see a code editor and a file browser. You need to open the terminal: + - Click the "hamburger" menu (☰) in the top-left corner. + - Go to **"Terminal" > "New Terminal"**. -```bash -# Fetch the latest changes from the base remote -git fetch base +4. **Run the Merge Commands:** + In the terminal, you will now run a series of Git commands. These are the same commands as the advanced method, but you are running them in the browser instead of on your local machine. + - **Add `base` as a remote:** This tells Git where to find the `attogram/base` repository. + ```bash + git remote add base https://github.com/attogram/base.git + ``` + - **Fetch and merge `base`:** This downloads the `base` repository and merges it into your project. + ```bash + git fetch base + git merge base/main --allow-unrelated-histories + ``` -# Merge the base/main branch into your current branch -# The --allow-unrelated-histories flag is necessary because your project -# and base do not share a common Git history. -git merge base/main --allow-unrelated-histories -``` +5. **Handle Merge Conflicts:** + If there are any merge conflicts, the Codespace will highlight the affected files in the file browser. + - Click on a conflicted file to open it. + - The editor will show you the conflicting changes with markers (`<<<<<<<`, `=======`, `>>>>>>>`). + - You can use the buttons provided by the editor (**"Accept Current Change"**, **"Accept Incoming Change"**, etc.) to resolve the conflicts. + - Once you have resolved the conflicts in a file, save it. -This will bring all the files from `base` into your project. +6. **Commit and Push the Changes:** + - Go to the **"Source Control"** tab on the left-hand side (it looks like a branching icon). + - Enter a commit message (e.g., "Merge attogram/base"). + - Click the checkmark icon to commit the changes. + - Click the **"Sync Changes"** button to push the changes to your repository on GitHub. -## 3. Handle Merge Conflicts +7. **Create a Pull Request:** + - Go back to your repository's main page on GitHub. + - You will see a notification to create a Pull Request from your recently pushed changes. Click on it, review the details, and create the PR. -It is highly likely that you will encounter merge conflicts, especially for files that exist in both your project and `base` (e.g., `.gitignore`, `README.md`). +--- -When a merge conflict occurs, Git will pause the merge process and mark the conflicting files. To resolve them: +## Advanced Method: Using the Command Line -1. **Identify Conflicting Files:** Run `git status` to see a list of files with conflicts. They will be marked as "unmerged". +This method is for users who are comfortable with the command line and have Git installed on their local machine. -2. **Open the Files:** Open each conflicting file in your code editor. You will see conflict markers: +### 1. Add `base` as a Remote - ``` - <<<<<<< HEAD - # Your existing .gitignore content - node_modules/ - ======= - # .gitignore content from base - .vscode/ - .devcontainer/ - >>>>>>> base/main - ``` +First, you need to add the `base` repository as a remote to your local Git repository. This allows you to fetch its branches and history. -3. **Resolve the Conflicts:** Edit the file to keep the version you want. You might want to keep your version, the `base` version, or a combination of both. For example, in the `.gitignore` conflict above, you would likely want to combine the entries from both: +Open your terminal, navigate to your project's root directory, and run the following command: - ``` - # Combined .gitignore - node_modules/ - .vscode/ - .devcontainer/ - ``` +```bash +git remote add base https://github.com/attogram/base.git +``` - Remove the `<<<<<<<`, `=======`, and `>>>>>>>` markers after editing. +### 2. Fetch and Merge `base` -4. **Stage the Resolved Files:** After resolving the conflicts in a file, stage it using `git add`: +Next, fetch the `base` repository's history and merge its `main` branch into your project's main branch. - ```bash - git add .gitignore - ``` +```bash +git fetch base +git merge base/main --allow-unrelated-histories +``` + +### 3. Handle Merge Conflicts -5. **Commit the Merge:** Once you have resolved all conflicts and staged all the conflicting files, commit the merge: +It is highly likely that you will encounter merge conflicts. To resolve them: +1. **Identify Conflicting Files:** Run `git status` to see a list of files with conflicts. +2. **Open the Files:** Open each conflicting file in your code editor and resolve the conflicts by editing the file and removing the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`). +3. **Stage the Resolved Files:** After resolving the conflicts, stage the files using `git add`. + ```bash + git add . + ``` +4. **Commit the Merge:** Once all conflicts are resolved, commit the merge. ```bash git commit ``` - A pre-populated commit message will appear. You can keep it as is or modify it. +### 4. Create a Pull Request -## 4. Create a Pull Request - -After the merge is complete and all conflicts are resolved, you should push the changes to your own repository and create a Pull Request (PR). This allows your team to review the changes before they are integrated into the main branch. +After the merge is complete, push the changes to your repository and create a Pull Request. 1. **Push Your Branch:** - ```bash git push origin your-branch-name ``` - -2. **Open a Pull Request:** Go to your repository on GitHub. You will see a prompt to create a new Pull Request from the branch you just pushed. Click on it, fill out the details, and create the PR. - -By following these steps, you can successfully merge the `base` repository into your existing project and manage any conflicts that arise. +2. **Open a Pull Request:** Go to your repository on GitHub. You will see a prompt to create a new Pull Request. Click on it, fill out the details, and create the PR.