Skip to content

Docs: Revise merge guide with web and CLI methods #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
attogram merged 1 commit into from
Aug 29, 2025
Merged

Docs: Revise merge guide with web and CLI methods #15

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 68 additions & 56 deletions docs/merging-base.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.