Skip to content

Commit 9a4bd36

Browse files
supermarsxsupermarsx
committed
Initial project setup with restore script and CI
Add OpenCore restoration script (restore.sh), test suite (tests/test_restore.sh), CI workflow for linting, formatting, and testing, .gitignore, and project documentation (readme.md). This establishes the foundation for an automated EFI bootloader recovery toolkit with testing and continuous integration.
1 parent 58a567b commit 9a4bd36

File tree

5 files changed

+623
-0
lines changed

5 files changed

+623
-0
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
lint:
11+
name: Lint (ShellCheck)
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout code
15+
uses: actions/checkout@v3
16+
17+
- name: Run ShellCheck
18+
uses: ludeeus/action-shellcheck@master
19+
with:
20+
scandir: "."
21+
severity: warning
22+
23+
format:
24+
name: Format (shfmt)
25+
runs-on: ubuntu-latest
26+
steps:
27+
- name: Checkout code
28+
uses: actions/checkout@v3
29+
30+
- name: Install shfmt
31+
run: sudo snap install shfmt
32+
33+
- name: Check Formatting
34+
run: shfmt -d -i 4 -ci .
35+
36+
test:
37+
name: Run Tests
38+
runs-on: ubuntu-latest
39+
steps:
40+
- name: Checkout code
41+
uses: actions/checkout@v3
42+
43+
- name: Run Test Suite
44+
run: |
45+
chmod +x restore.sh
46+
chmod +x tests/test_restore.sh
47+
cd tests
48+
./test_restore.sh

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/tests/test_env
2+
/tests/Volumes

‎readme.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# OpenCore Restoration Kit
2+
3+
## 🚨 Emergency Boot Rescue
4+
5+
**Did you accidentally update macOS and lose access to your system?**
6+
7+
This repository provides a "Rescue Kit" to help you boot back into macOS when your OpenCore installation has been overwritten, bypassed, or corrupted during a system update.
8+
9+
---
10+
11+
## ⚡ Choose Your Recovery Method
12+
13+
Select the method that best fits your situation:
14+
15+
| Method | Requirements | Difficulty | Best For |
16+
| :--- | :--- | :--- | :--- |
17+
| **[1. Rescue USB](#1-rescue-usb-method-recommended)** | Another PC/Mac + USB Drive | ⭐ Easy | Most reliable method. |
18+
| **[2. Local Recovery](#2-local-recovery-no-usb-no-internet)** | `OpenCore-Patcher` app on disk | ⭐⭐ Medium | No USB or Internet needed. |
19+
| **[3. Internet Recovery (Official)](#3-internet-recovery-no-usb-with-internet)** | Internet connection in Recovery | ⭐⭐⭐ Hard | Downloads generic OpenCore. |
20+
| **[4. Internet Rescue Kit (Repo)](#4-internet-recovery-using-this-rescue-kit)** | Internet connection in Recovery | ⭐⭐ Medium | Downloads this specific rescue kit. |
21+
22+
---
23+
24+
## 1. Rescue USB Method (Recommended)
25+
26+
**Requirements:** Another computer (Windows/Mac/Linux) and a USB drive.
27+
28+
1. **Prepare USB:** Format a USB drive as **FAT32**.
29+
2. **Copy Files:** Copy the **`EFI`** folder from the `BOOTEFIX64` folder in this repository to the **root** of the USB drive.
30+
3. **Boot:**
31+
* Insert USB into the broken Mac.
32+
* Hold **Option (Alt)** while powering on.
33+
* Select **"EFI Boot"** (OpenCore logo).
34+
* Select your macOS disk to boot.
35+
4. **Fix:** Once in macOS, run OpenCore Patcher and "Install to Disk" to fix the internal drive.
36+
37+
---
38+
39+
## 2. Local Recovery (No USB, No Internet)
40+
41+
**Requirements:** You must have the **OpenCore Legacy Patcher** app installed in your Applications folder on the broken Mac.
42+
43+
1. Boot into **macOS Recovery** (Hold `Cmd+R` or Power button).
44+
2. Open **Terminal** (Utilities > Terminal).
45+
3. **Identify your disks:**
46+
```bash
47+
diskutil list
48+
```
49+
*Note your EFI partition (e.g., `disk0s1`) and macOS Data volume identifier (e.g., `disk1s1` - look for "APFS Data").*
50+
4. **Unlock Data Volume (If Encrypted):**
51+
If you don't see your volume in `/Volumes` or it is encrypted (FileVault), unlock it:
52+
```bash
53+
# Replace disk1s1 with your Data volume identifier
54+
diskutil apfs unlockVolume disk1s1
55+
```
56+
*Enter your macOS user password when prompted.*
57+
5. **Mount EFI:**
58+
```bash
59+
diskutil mount disk0s1
60+
```
61+
6. **Copy EFI from your Applications folder:**
62+
```bash
63+
# Navigate to the Patcher's resources
64+
cd "/Volumes/Macintosh HD/Applications/OpenCore-Patcher.app/Contents/Resources"
65+
66+
# Copy the EFI folder to your EFI partition
67+
cp -R EFI /Volumes/EFI/
68+
```
69+
7. **Clear NVRAM & Reboot:**
70+
It is critical to clear NVRAM so the firmware forgets the old broken boot entries.
71+
```bash
72+
nvram -c
73+
```
74+
Then, fully **shutdown** and power on again (cold boot) to ensure the new settings take effect.
75+
```bash
76+
shutdown -h now
77+
```
78+
79+
---
80+
81+
## 3. Internet Recovery (No USB, With Internet)
82+
83+
**Requirements:** Working Wi-Fi or Ethernet in Recovery Mode.
84+
85+
1. Boot into **macOS Recovery** and connect to Wi-Fi (top right corner).
86+
2. Open **Terminal**.
87+
3. **Mount EFI:**
88+
```bash
89+
diskutil mount disk0s1
90+
```
91+
4. **Download OpenCore:**
92+
```bash
93+
cd /Volumes/EFI
94+
# Download OpenCore (Example for v1.6.0 - check for latest version URL)
95+
curl -L -O https://github.com/acidanthera/OpenCorePkg/releases/download/1.6.0/OpenCore-1.6.0-RELEASE.zip
96+
unzip OpenCore-*.zip
97+
```
98+
5. **Install:**
99+
* *Warning: This installs a generic config. Only use this if you know how to configure it or just need the .efi files.*
100+
```bash
101+
cp -R X64/EFI /Volumes/EFI/
102+
```
103+
*(See the [Detailed Guide](restoration-guide.md) for properly configuring `BOOTx64.efi`)*
104+
6. **Clear NVRAM & Reboot:**
105+
```bash
106+
nvram -c
107+
shutdown -h now
108+
```
109+
*Perform a cold boot (shutdown then power on).*
110+
111+
---
112+
113+
## 4. Internet Recovery (Using this Rescue Kit)
114+
115+
**Requirements:** Working Wi-Fi or Ethernet in Recovery Mode.
116+
117+
1. Boot into **macOS Recovery** and connect to Wi-Fi.
118+
2. Open **Terminal**.
119+
3. **Mount EFI:**
120+
```bash
121+
diskutil mount disk0s1
122+
```
123+
4. **Download this Rescue Kit:**
124+
```bash
125+
cd /tmp
126+
curl -L -o opencore-restore.zip https://codeload.github.com/supermarsx/opencore-restore/zip/refs/heads/main
127+
unzip opencore-restore.zip
128+
```
129+
5. **Run the Automated Restore Script:**
130+
We have included a script to automate the process (detects EFI, backs up old files, installs new ones, and clears NVRAM).
131+
```bash
132+
cd opencore-restore-main
133+
chmod +x restore.sh
134+
./restore.sh
135+
```
136+
*Follow the on-screen prompts.*
137+
138+
---
139+
140+
## 📚 Detailed Manual Guide
141+
142+
For complex scenarios, troubleshooting, and detailed explanations of every command, please read our full **[Restoration Guide](restoration-guide.md)**.
143+
144+
## ⚠️ Disclaimer & No Warranty
145+
146+
**YOU ARE ON YOUR OWN.**
147+
148+
This software and guide are provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.
149+
150+
* **Risk of Data Loss:** Modifying EFI partitions and bootloaders carries a risk of rendering your system unbootable or causing data loss.
151+
* **Backup Required:** Always backup your data before performing system modifications.
152+
* **Not Official:** This is a community-maintained rescue kit and is not affiliated with Apple Inc. or the OpenCore project.

0 commit comments

Comments
 (0)