-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathgithub-guide.html
More file actions
471 lines (412 loc) · 27.6 KB
/
Copy pathgithub-guide.html
File metadata and controls
471 lines (412 loc) · 27.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>GitHub Essentials — Git & GitHub Handbook</title>
<meta name="description"
content="Create a repo on GitHub from the web or the terminal, push a whole folder for the first time, clone or fork other projects, and manage public vs private repos.">
<link rel="stylesheet" href="style.css">
</head>
<body>
<button id="navToggle" class="nav-toggle" aria-label="Toggle table of contents">☰ Contents</button>
<div id="navOverlay" class="nav-overlay"></div>
<div class="app">
<nav class="sidebar" id="sidebar" aria-label="Table of contents">
<div class="sidebar-inner">
<a href="index.html" class="brand">
<span class="brand-mark">git</span>
<span class="brand-sub">& github</span>
</a>
<p class="sidebar-tagline">A no-nonsense guide for people who've never touched a terminal.</p>
<div class="site-nav">
<p class="site-nav-label">Guides</p>
<ul class="site-nav-list">
<li><a href="index.html">Home</a></li>
<li><a href="git-basics.html">1. Git Basics</a></li>
<li><a href="github-guide.html" class="current">2. GitHub Essentials</a></li>
<li><a href="collaboration.html">3. Working with Others</a></li>
<li><a href="profile.html">4. Profile & Portfolio</a></li>
<li><a href="tips-tricks.html">5. Tips & Tricks</a></li>
</ul>
</div>
<p class="toc-label">On this page</p>
<ul class="toc-list">
<li><a href="#connect">HTTPS vs SSH</a></li>
<li><a href="#newrepo-web">New Repo on the Web</a></li>
<li><a href="#push-folder">Push an Existing Folder</a></li>
<li><a href="#cli">New Repo with GitHub CLI</a></li>
<li><a href="#clonefork">Cloning vs Forking</a></li>
<li><a href="#visibility">Public vs Private</a></li>
<li><a href="#desktop">GitHub Desktop</a></li>
<li><a href="#errors2">Common Errors</a></li>
<li><a href="#cheat2">Cheat Sheet</a></li>
</ul>
<a class="sidebar-footer-link" href="https://www.linkedin.com/in/muhammad-hamza-naqi-569741403/"
target="_blank" rel="noopener noreferrer">Connect with the author →</a>
</div>
</nav>
<main class="main" id="top">
<div class="content">
<header class="hero">
<p class="eyebrow">Part 2 of 5 · Beginner's Handbook</p>
<h1>GitHub Essentials</h1>
<p class="lede">This part is about the actual GitHub website and how your local Git repo talks
to it — creating repos, pushing a real project folder for the first time, and grabbing
other people's code. If you haven't installed Git yet, do
<a href="git-basics.html">Part 1 — Git Basics</a> first.</p>
</header>
<hr>
<div class="note-card">
<p><b>Jumping in here?</b> This chapter assumes you already know what a repo, commit, and
branch are, and that Git is installed on your machine. If any of that sounds unfamiliar,
<a href="git-basics.html">Part 1 — Git Basics</a> covers it in five minutes.</p>
</div>
<section id="connect">
<h3><span class="num">01</span> HTTPS vs SSH — Two Ways to Connect</h3>
<p>Before pushing anything, GitHub needs to know it's really you. There are two common ways to
authenticate from your terminal — both just log you in, they don't change what Git
itself does:</p>
<ul>
<li>
<b>HTTPS</b> — the same <code>https://</code> you already know from web addresses.
GitHub will ask you to sign in through the browser the first time, or use a
<b>Personal Access Token</b> (a special auto-generated password meant just for this, which
you can revoke any time) instead of your real password. Good default if you're just
starting out.
</li>
<li>
<b>SSH</b> (Secure Shell) — uses a "key pair" stored on your computer instead of a
password: one half stays secret on your machine, the other half you give to GitHub, and
the two prove to each other that it's really you. Slightly more setup, but you never type
a password again to push or pull — especially nice on Linux or if you push often.
</li>
</ul>
<p>To set up SSH, generate a key and add the public half to GitHub:</p>
<div class="term">
<div class="term-bar"><span class="dot dot-r"></span><span class="dot dot-y"></span><span
class="dot dot-g"></span><span class="term-title">terminal</span></div>
<div class="term-body">
<div class="line"><span class="prompt">$</span><span class="cmd">ssh-keygen -t ed25519 -C
"you@example.com"</span></div>
<div class="line output">accept the default file location, press Enter for no
passphrase (or set one)</div>
<div class="line"><span class="prompt">$</span><span class="cmd">cat
~/.ssh/id_ed25519.pub</span></div>
</div>
</div>
<p>Copy the printed key, then on GitHub go to <b>Settings → SSH and GPG keys → New SSH key</b>
and paste it in. Test the connection:</p>
<div class="term">
<div class="term-bar"><span class="dot dot-r"></span><span class="dot dot-y"></span><span
class="dot dot-g"></span><span class="term-title">terminal</span></div>
<div class="term-body">
<div class="line"><span class="prompt">$</span><span class="cmd">ssh -T
git@github.com</span></div>
<div class="line output">Hi username! You've successfully authenticated...</div>
</div>
</div>
<p>From then on, use <code>git@github.com:username/repo.git</code> style URLs instead of
<code>https://github.com/...</code> when cloning or adding a remote.</p>
</section>
<hr>
<section id="newrepo-web">
<h3><span class="num">02</span> Creating a New Repo on GitHub (Web)</h3>
<p>This is the most common starting point for a brand-new project:</p>
<ul>
<li>Log in to GitHub and click the <b>+</b> icon top-right → <b>New repository</b>.</li>
<li>Give it a short, clear name — no spaces, hyphens are fine (<code>weather-app</code>).</li>
<li>Choose <b>Public</b> or <b>Private</b> (you can change this later, see below).</li>
<li>
If this is a brand-new project with nothing local yet, tick <b>Add a README file</b> so
the repo isn't completely empty. A README is just a text file (written in a simple
format called <b>Markdown</b> — more on that in <a href="profile.html#sections">Part
4</a>) that GitHub displays front-and-center on the repo's page. If you already have
a project folder on your computer, leave everything unticked — you'll connect it
yourself in the next section.
</li>
<li>Click <b>Create repository</b>. GitHub shows you the repo's URL — keep that tab open.</li>
</ul>
</section>
<hr>
<section id="push-folder">
<h3><span class="num">03</span> Pushing a Whole Project Folder for the First Time</h3>
<p>The most common beginner question: <i>"I have a folder full of code on my computer — how do I
get all of it onto GitHub?"</i> Here's the full path, assuming you created an <b>empty</b>
repo on GitHub (no README, no .gitignore):</p>
<ul>
<li>
Open a terminal <b>inside your project folder</b> (the one with all your files):
<div class="term">
<div class="term-bar"><span class="dot dot-r"></span><span
class="dot dot-y"></span><span class="dot dot-g"></span><span
class="term-title">terminal</span></div>
<div class="term-body">
<div class="line"><span class="prompt">$</span><span class="cmd">cd
path/to/your-project</span></div>
</div>
</div>
</li>
<li>
Turn it into a Git repo (skip this if it already has a hidden <code>.git</code> folder):
<div class="term">
<div class="term-bar"><span class="dot dot-r"></span><span
class="dot dot-y"></span><span class="dot dot-g"></span><span
class="term-title">terminal</span></div>
<div class="term-body">
<div class="line"><span class="prompt">$</span><span class="cmd">git init -b
main</span></div>
</div>
</div>
</li>
<li>
Stage and commit everything in the folder:
<div class="term">
<div class="term-bar"><span class="dot dot-r"></span><span
class="dot dot-y"></span><span class="dot dot-g"></span><span
class="term-title">terminal</span></div>
<div class="term-body">
<div class="line"><span class="prompt">$</span><span class="cmd">git add .</span>
</div>
<div class="line"><span class="prompt">$</span><span class="cmd">git commit -m
"initial commit"</span></div>
</div>
</div>
</li>
<li>
Point your local repo at the empty GitHub repo you created (copy the URL from GitHub's
"Quick setup" page — HTTPS or SSH, matching whichever you set up above):
<div class="term">
<div class="term-bar"><span class="dot dot-r"></span><span
class="dot dot-y"></span><span class="dot dot-g"></span><span
class="term-title">terminal</span></div>
<div class="term-body">
<div class="line"><span class="prompt">$</span><span class="cmd">git remote add
origin git@github.com:username/your-project.git</span></div>
</div>
</div>
</li>
<li>
Push every file to GitHub:
<div class="term">
<div class="term-bar"><span class="dot dot-r"></span><span
class="dot dot-y"></span><span class="dot dot-g"></span><span
class="term-title">terminal</span></div>
<div class="term-body">
<div class="line"><span class="prompt">$</span><span class="cmd">git push -u
origin main</span></div>
</div>
</div>
<p style="margin-top:-6px;">Refresh the GitHub page — your entire folder structure,
subfolders included, should now be there.</p>
</li>
</ul>
<div class="error-card">
<span class="error-msg">error: failed to push some refs — remote contains work that you do
not have locally</span>
<p class="error-fix">This happens if you ticked "Add a README" when creating the repo. Run
<code>git pull origin main --allow-unrelated-histories</code>, resolve any conflict, then
push again.
</p>
</div>
</section>
<hr>
<section id="cli">
<h3><span class="num">04</span> Creating a Repo from the Terminal (GitHub CLI)</h3>
<p><b>CLI</b> stands for <b>Command-Line Interface</b> — just a technical way of saying "a tool
you control by typing commands," as opposed to clicking around a website. The
<b>GitHub CLI</b> is a separate program (its command is <code>gh</code>, distinct from the
<code>git</code> command you've been using) that lets you do most GitHub-website tasks —
creating repos, opening pull requests, and more — without ever leaving your terminal. It's
optional: everything it does can also be done by clicking around the GitHub website, this is
just a faster path once you're comfortable in a terminal. Install it first:</p>
<div class="term">
<div class="term-bar"><span class="dot dot-r"></span><span class="dot dot-y"></span><span
class="dot dot-g"></span><span class="term-title">terminal</span></div>
<div class="term-body">
<div class="line comment"># macOS</div>
<div class="line"><span class="prompt">$</span><span class="cmd">brew install gh</span>
</div>
<div class="line comment"># Windows (winget)</div>
<div class="line"><span class="prompt">$</span><span class="cmd">winget install
--id GitHub.cli</span></div>
<div class="line comment"># Ubuntu / Debian — see cli.github.com for the full script</div>
<div class="line"><span class="prompt">$</span><span class="cmd">sudo apt install gh</span>
</div>
</div>
</div>
<p>Log in once (it walks you through browser authentication):</p>
<div class="term">
<div class="term-bar"><span class="dot dot-r"></span><span class="dot dot-y"></span><span
class="dot dot-g"></span><span class="term-title">terminal</span></div>
<div class="term-body">
<div class="line"><span class="prompt">$</span><span class="cmd">gh auth login</span>
</div>
</div>
</div>
<p>Now you can create a repo and push your current folder to it in one go, without ever opening a
browser:</p>
<div class="term">
<div class="term-bar"><span class="dot dot-r"></span><span class="dot dot-y"></span><span
class="dot dot-g"></span><span class="term-title">terminal</span></div>
<div class="term-body">
<div class="line"><span class="prompt">$</span><span class="cmd">cd
path/to/your-project</span></div>
<div class="line"><span class="prompt">$</span><span class="cmd">git init -b main
&& git add . && git commit -m "initial commit"</span></div>
<div class="line"><span class="prompt">$</span><span class="cmd">gh repo create
your-project --public --source=. --remote=origin --push</span></div>
</div>
</div>
<p>Swap <code>--public</code> for <code>--private</code> if you don't want it visible to
everyone. That one command creates the repo on GitHub, links it as <code>origin</code>, and
pushes your first commit — the web UI steps above, compressed into one line.</p>
</section>
<hr>
<section id="clonefork">
<h3><span class="num">05</span> Cloning vs Forking Someone Else's Project</h3>
<p>Two different things beginners often mix up:</p>
<ul>
<li>
<b>Clone</b> — download a copy of any repo you can already see (including your own)
to work on locally. You get the code, but if you don't have write access to the original,
you can't push changes back to it.
<div class="term">
<div class="term-bar"><span class="dot dot-r"></span><span
class="dot dot-y"></span><span class="dot dot-g"></span><span
class="term-title">terminal</span></div>
<div class="term-body">
<div class="line"><span class="prompt">$</span><span class="cmd">git clone
https://github.com/someone/their-repo.git</span></div>
</div>
</div>
</li>
<li>
<b>Fork</b> — make your own copy of someone else's repo <i>under your own GitHub
account</i>. You get full write access to your fork, so you can make changes, commit,
and push freely, then later propose those changes back to the original via a pull request
(covered in <a href="collaboration.html">Part 3</a>).
</li>
</ul>
<p>Click <b>Fork</b> on the repo's GitHub page to create your copy, then clone <i>your fork</i>
(not the original) to work on it locally:</p>
<div class="term">
<div class="term-bar"><span class="dot dot-r"></span><span class="dot dot-y"></span><span
class="dot dot-g"></span><span class="term-title">terminal</span></div>
<div class="term-body">
<div class="line"><span class="prompt">$</span><span class="cmd">git clone
git@github.com:your-username/their-repo.git</span></div>
</div>
</div>
</section>
<hr>
<section id="visibility">
<h3><span class="num">06</span> Public vs Private (and Changing Later)</h3>
<ul>
<li><b>Public</b> — anyone can see the code (great for portfolios, open source).</li>
<li><b>Private</b> — only you and people you explicitly invite can see it.</li>
</ul>
<p>You're not locked into your choice. To switch later: open the repo on GitHub → <b>Settings</b>
→ scroll to the <b>Danger Zone</b> at the bottom → <b>Change visibility</b>. The same Danger
Zone is also where you rename, transfer ownership of, or permanently delete a repo —
GitHub makes you type the repo name to confirm deletion, so it's hard to do by accident.</p>
<div class="note-card">
<p><b>Heads up:</b> if a repo was ever public, assume anything pushed to it — including
old commits — may have been seen or cached somewhere. Making it private afterward
hides it going forward, but doesn't retroactively erase copies others may have made.</p>
</div>
</section>
<hr>
<section id="desktop">
<h3><span class="num">07</span> Prefer a GUI? GitHub Desktop</h3>
<p>This handbook is terminal-first because typing commands makes the underlying model click
faster, but you don't have to live in the terminal forever. A <b>GUI</b> (Graphical User
Interface — the technical term for a point-and-click app) can do the same job.
<b>GitHub Desktop</b> (from
<a href="https://desktop.github.com" target="_blank" rel="noopener noreferrer">desktop.github.com</a>)
gives you that same add / commit / push / pull / branch workflow, just with buttons instead
of commands — useful for reviewing changes visually or for teammates who aren't comfortable
with a terminal yet. Most editors (VS Code, JetBrains IDEs) also have built-in Git panels that cover
the everyday cycle without needing a separate app at all.</p>
</section>
<hr>
<section id="errors2">
<h3><span class="num">08</span> Common Errors & Fixes</h3>
<div class="error-card">
<span class="error-msg">remote: Support for password authentication was removed</span>
<p class="error-fix">GitHub no longer accepts your account password over HTTPS. Generate a
<b>Personal Access Token</b> (Settings → Developer settings → Personal access tokens) and
use that as your password, or switch to SSH.
</p>
</div>
<div class="error-card">
<span class="error-msg">fatal: remote origin already exists</span>
<p class="error-fix">The folder is already linked to a remote. Either remove it with
<code>git remote remove origin</code> and add the correct one, or update it directly with
<code>git remote set-url origin <URL></code>.
</p>
</div>
<div class="error-card">
<span class="error-msg">Permission denied (publickey)</span>
<p class="error-fix">Your SSH key isn't set up or isn't added to GitHub. Re-check the steps
in <a href="#connect">HTTPS vs SSH</a> above, and confirm with
<code>ssh -T git@github.com</code>.
</p>
</div>
</section>
<hr>
<section id="cheat2">
<h3><span class="num">09</span> GitHub Essentials Cheat Sheet</h3>
<table class="git-cheat-sheet">
<tr>
<td class="command">gh auth login</td>
<td>Log the GitHub CLI into your account</td>
</tr>
<tr>
<td class="command">gh repo create name --public --source=. --push</td>
<td>Create a repo on GitHub and push the current folder to it, in one step</td>
</tr>
<tr>
<td class="command">gh repo clone user/repo</td>
<td>Clone a repo using the CLI instead of a full git URL</td>
</tr>
<tr>
<td class="command">gh repo view --web</td>
<td>Open the current repo's GitHub page in your browser</td>
</tr>
<tr>
<td class="command">git remote add origin <URL></td>
<td>Link a local folder to a GitHub repo for the first time</td>
</tr>
<tr>
<td class="command">git remote -v</td>
<td>Show which GitHub URL(s) this folder is connected to</td>
</tr>
<tr>
<td class="command">git remote set-url origin <URL></td>
<td>Change the GitHub URL if you already have one set</td>
</tr>
<tr>
<td class="command">git clone <URL></td>
<td>Download a full copy of any repo you can see</td>
</tr>
</table>
</section>
<hr>
<div class="note-card">
<p><b>Ready to work with other people?</b> Head to <a href="collaboration.html">Part 3 — Working
with Others</a> to add collaborators, open pull requests, and resolve merge conflicts.</p>
</div>
<hr>
<footer class="page-footer">
<p>Prepared by <b>Muhammad Hamza Naqi</b></p>
<a class="linkedin-btn" href="https://www.linkedin.com/in/muhammad-hamza-naqi-569741403/"
target="_blank" rel="noopener noreferrer">Connect on LinkedIn</a>
</footer>
</div>
</main>
</div>
<button id="backTop" class="back-top" aria-label="Back to top">↑</button>
<script src="script.js"></script>
</body>
</html>