Skip to content

Commit 155048c

Browse files
irsdlirsdl
committed
Add comprehensive guide for creating and maintaining custom forks
Added detailed documentation on how to: - Set up a custom fork with upstream PRs applied - Configure git remotes safely (upstream as read-only) - Apply upstream PRs using multiple methods - Add custom enhancements - Push to personal fork only (not to upstream) - Maintain the fork and sync with upstream - Recommended branch strategy - Safety tips and best practices - Troubleshooting common issues - Complete example workflow This guide ensures others can replicate the custom fork setup and prevents accidental pushes to the upstream repository.
1 parent 6b03f79 commit 155048c

File tree

1 file changed

+260
-0
lines changed

1 file changed

+260
-0
lines changed

‎README.md‎

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,266 @@ git fetch upstream
5151
# Visit https://github.com/bitquark/shortscan/pulls to verify PR status
5252
```
5353

54+
### How to Create Your Own Custom Fork
55+
56+
If you want to create your own enhanced version of shortscan with upstream PRs applied, follow these steps:
57+
58+
#### 1. Initial Setup
59+
60+
```bash
61+
# Fork the repository on GitHub (click "Fork" button on bitquark/shortscan)
62+
# Then clone YOUR fork
63+
git clone https://github.com/YOUR_USERNAME/shortscan.git
64+
cd shortscan
65+
66+
# Add upstream remote (read-only)
67+
git remote add upstream https://github.com/bitquark/shortscan.git
68+
git remote set-url --push upstream no-push # Prevent accidental pushes to upstream
69+
70+
# Verify remotes
71+
git remote -v
72+
# Should show:
73+
# origin https://github.com/YOUR_USERNAME/shortscan.git (fetch)
74+
# origin https://github.com/YOUR_USERNAME/shortscan.git (push)
75+
# upstream https://github.com/bitquark/shortscan.git (fetch)
76+
# upstream no-push (push)
77+
```
78+
79+
#### 2. Create Enhanced Branch
80+
81+
```bash
82+
# Fetch all branches and PRs
83+
git fetch upstream
84+
git fetch origin
85+
86+
# Create your custom branch based on upstream/main
87+
git checkout -b merge-upstream-prs upstream/main
88+
89+
# Or base it on a specific tag/version
90+
git checkout -b merge-upstream-prs v0.9.2
91+
```
92+
93+
#### 3. Apply Upstream PRs
94+
95+
```bash
96+
# Method 1: Cherry-pick from PR branches (if available)
97+
git fetch upstream pull/16/head:pr-16
98+
git fetch upstream pull/23/head:pr-23
99+
git fetch upstream pull/24/head:pr-24
100+
101+
git cherry-pick pr-16
102+
git cherry-pick pr-23
103+
git cherry-pick pr-24
104+
105+
# Method 2: Manually apply patches from PR diffs
106+
# Visit the PR page, download the .patch file, then:
107+
curl -L https://github.com/bitquark/shortscan/pull/16.patch | git am
108+
curl -L https://github.com/bitquark/shortscan/pull/23.patch | git am
109+
curl -L https://github.com/bitquark/shortscan/pull/24.patch | git am
110+
111+
# Method 3: Manual merge (if conflicts occur)
112+
git merge pr-16
113+
# Resolve conflicts if any
114+
git merge pr-23
115+
git merge pr-24
116+
```
117+
118+
#### 4. Add Your Custom Enhancements
119+
120+
```bash
121+
# Make your custom changes
122+
nano pkg/shortscan/shortscan.go
123+
124+
# Commit your changes
125+
git add .
126+
git commit -m "Add custom enhancements
127+
128+
- Feature 1
129+
- Feature 2
130+
- etc."
131+
132+
# Build and test
133+
go build ./cmd/shortscan
134+
./shortscan --help
135+
```
136+
137+
#### 5. Update Documentation
138+
139+
```bash
140+
# Update README with fork information
141+
nano README.md
142+
143+
# Add section about:
144+
# - Applied PRs
145+
# - Custom features
146+
# - How to maintain the fork
147+
148+
git add README.md
149+
git commit -m "Document custom fork and applied PRs"
150+
```
151+
152+
#### 6. Push to Your Fork
153+
154+
```bash
155+
# First time push with tracking
156+
git push -u origin merge-upstream-prs
157+
158+
# Subsequent pushes
159+
git push
160+
161+
# Push all branches
162+
git push origin --all
163+
```
164+
165+
#### 7. Maintain Your Fork
166+
167+
**Keep main branch synced with upstream:**
168+
```bash
169+
git checkout main
170+
git fetch upstream
171+
git merge upstream/main
172+
git push origin main
173+
```
174+
175+
**Update your custom branch with upstream changes:**
176+
```bash
177+
git checkout merge-upstream-prs
178+
git fetch upstream
179+
180+
# Option 1: Rebase (cleaner history)
181+
git rebase upstream/main
182+
183+
# Option 2: Merge (preserves history)
184+
git merge upstream/main
185+
186+
# Resolve any conflicts, then push
187+
git push origin merge-upstream-prs --force-with-lease # If rebased
188+
# or
189+
git push origin merge-upstream-prs # If merged
190+
```
191+
192+
**Check if upstream PRs were merged:**
193+
```bash
194+
# Fetch latest upstream
195+
git fetch upstream
196+
197+
# Check if PRs are in upstream/main now
198+
git log upstream/main --oneline | grep -i "rate limit"
199+
git log upstream/main --oneline | grep -i "source code"
200+
201+
# If PRs are merged upstream, you can remove them from your branch
202+
# and just sync with upstream/main
203+
```
204+
205+
#### 8. Branch Strategy
206+
207+
We recommend this structure:
208+
209+
```
210+
main ← Synced with upstream/main (pristine)
211+
merge-upstream-prs ← Your enhanced version (PRs + custom features)
212+
feature/custom-1 ← Individual feature branches (optional)
213+
feature/custom-2 ← Individual feature branches (optional)
214+
```
215+
216+
**Workflow:**
217+
1. Keep `main` in sync with `upstream/main`
218+
2. Work on `merge-upstream-prs` for your enhanced version
219+
3. Create feature branches for experimental features
220+
4. Merge feature branches into `merge-upstream-prs` when ready
221+
222+
#### 9. Safety Tips
223+
224+
✅ **DO:**
225+
- Always use `-u origin` when pushing new branches
226+
- Keep `main` branch clean (synced with upstream)
227+
- Document all custom changes in README
228+
- Use `.gitignore` to prevent committing sensitive data
229+
- Test thoroughly after applying PRs
230+
231+
❌ **DON'T:**
232+
- Push to `upstream` remote (set to `no-push` for safety)
233+
- Commit sensitive data (credentials, API keys, etc.)
234+
- Force push to shared branches
235+
- Modify `main` branch directly
236+
237+
#### 10. Troubleshooting
238+
239+
**Conflict during PR merge:**
240+
```bash
241+
# See what conflicts exist
242+
git status
243+
244+
# Edit conflicting files
245+
nano pkg/shortscan/shortscan.go
246+
247+
# Mark as resolved and continue
248+
git add pkg/shortscan/shortscan.go
249+
git merge --continue
250+
# or
251+
git rebase --continue
252+
```
253+
254+
**Need to undo last commit:**
255+
```bash
256+
# Undo commit but keep changes
257+
git reset --soft HEAD~1
258+
259+
# Undo commit and discard changes
260+
git reset --hard HEAD~1
261+
```
262+
263+
**Accidentally pushed to wrong remote:**
264+
```bash
265+
# This won't work if upstream is set to no-push (good!)
266+
# But if you need to delete from origin:
267+
git push origin --delete branch-name
268+
```
269+
270+
### Example: Complete Fork Setup
271+
272+
Here's a complete example workflow:
273+
274+
```bash
275+
# 1. Fork on GitHub, then clone
276+
git clone https://github.com/yourusername/shortscan.git
277+
cd shortscan
278+
279+
# 2. Setup remotes
280+
git remote add upstream https://github.com/bitquark/shortscan.git
281+
git remote set-url --push upstream no-push
282+
283+
# 3. Create custom branch
284+
git checkout -b merge-upstream-prs upstream/main
285+
286+
# 4. Fetch and apply PRs
287+
git fetch upstream pull/16/head:pr-16
288+
git fetch upstream pull/23/head:pr-23
289+
git fetch upstream pull/24/head:pr-24
290+
git merge pr-16
291+
git merge pr-23
292+
git merge pr-24
293+
294+
# 5. Add custom features
295+
# ... make your changes ...
296+
git add .
297+
git commit -m "Add custom enhancements"
298+
299+
# 6. Update README
300+
nano README.md
301+
git add README.md
302+
git commit -m "Document custom fork"
303+
304+
# 7. Push to your fork
305+
git push -u origin merge-upstream-prs
306+
307+
# 8. Build and use
308+
go build ./cmd/shortscan
309+
./shortscan -R -w wordlist.txt http://example.com/
310+
```
311+
312+
Now you have a fully documented, maintainable custom fork! 🎉
313+
54314
## Functionality
55315

56316
Shortscan is designed to quickly determine which files with short filenames exist on an IIS webserver. Once a short filename has been identified the tool will try to automatically identify the full filename.

0 commit comments

Comments
 (0)