Introduction to GitHub

What GitHub Adds to Git

Git already gives you history, branches and merging. What it does not give you is a place for those things to meet other people. There is no built-in way to say "please review this before it goes into main", no list of known bugs, no automatic test run, and no address you can send someone. GitHub is a website that hosts Git repositories and builds all of that on top.

It is worth being precise about the split, because it decides where each problem gets solved. Git handles commits, branches, merges and history — all of it on your machine. GitHub handles hosting, access control, pull requests, code review, issue tracking, automation and discussion. GitLab, Bitbucket and Codeberg offer the same kind of layer; GitHub is simply where most open-source work and most job-relevant collaboration happens.

For a student there is a third thing GitHub provides that nobody mentions in the documentation: a public record. A profile with real repositories, honest commit history and readable READMEs is evidence that you have built things. When you apply for an internship and paste a GitHub link, whoever opens it can see the project, read the code and see that you worked on it over eight weeks rather than assembling it the night before. That is more persuasive than a line on a resume, and it costs nothing beyond pushing work you were doing anyway.

• Hosting — an off-site copy of your repository that survives a dead laptop
• Pull requests — propose changes and have them reviewed before they are merged
• Issues — a shared to-do list of bugs, features and tasks, linked to the code
• Actions — run tests, checks and deployments automatically when code is pushed
• Projects — boards for planning who is doing what
• Pages — publish a static website straight from a repository
• Access control — decide who can read, who can push, and what main requires

Creating a Repository and Connecting It

There are two directions, and mixing them up produces the most common beginner error on GitHub. Either you create the repository on GitHub first and clone it down, or you already have a local repository and connect it to an empty one on GitHub.

Starting on GitHub is the easier path. Click New repository, give it a name, and let GitHub add a README, a licence and a .gitignore from its template list. Then git clone the URL. Cloning sets up the origin remote and the tracking branch automatically, so git push works from the first commit with no further configuration.

Starting locally takes one extra step. Create the repository on GitHub without a README or any other file — this matters — then add it as a remote and push. If you let GitHub create a README while your local repository already has commits, the two histories have nothing in common, and your first push is rejected with a message about unrelated histories. The clean fix is to create the GitHub side empty. If you have already made that mistake, git pull --allow-unrelated-histories will stitch them together, usually with a conflict in the README to resolve by hand.

The -M main in the standard instructions simply renames your current branch to main before pushing, which matters if your Git was never configured with init.defaultBranch and started you on master.

# Direction 1: created on GitHub, cloned down (easiest)
git clone git@github.com:ananya/fest-website.git
cd fest-website
# origin and branch tracking are already set up

# Direction 2: existing local project -> new EMPTY GitHub repository
git remote add origin git@github.com:ananya/fest-website.git
git branch -M main            # rename current branch to main
git push -u origin main

# The error you get when the GitHub side was NOT empty
# ! [rejected] main -> main (fetch first)
# fatal: refusing to merge unrelated histories
git pull origin main --allow-unrelated-histories
#   resolve the README conflict, commit, then
git push -u origin main

# The GitHub CLI can do the whole thing in one line
gh repo create fest-website --public --source=. --push

The README Is the Most Important File

GitHub renders the file called README.md directly on the repository's front page. It is the first and often the only thing anybody reads, and for a student project it does more work than any other file in the repository.

Most college project READMEs say nothing useful — a project title and the word "project". Compare that to one that explains in three sentences what the software does, shows a screenshot, and lists the exact commands needed to run it. The second one can be evaluated by a stranger in two minutes. The first one requires them to read your source code to find out what it even is, and most people will not bother.

The .md extension means Markdown, a small formatting language you will use constantly on GitHub — it is also what issues, pull request descriptions and comments are written in. It is worth twenty minutes: # for headings, **bold**, - for bullets, backticks for code, triple backticks for code blocks, and [text](url) for links.

Two other files GitHub treats specially are worth adding. LICENSE states what others may legally do with your code — without one, strictly speaking nobody has permission to use it at all. .gitignore you already know; GitHub offers ready-made ones for every common language when you create the repository.

• What the project does, in two or three plain sentences at the top
• A screenshot or short demo clip — for anything with a user interface this is the highest-value item in the file
• Tech stack, so a reader knows immediately whether it is React, Django or plain PHP
• Setup steps that actually work on a clean machine, including how to create the .env file
• How to run it, and how to run the tests if there are any
• Features implemented, and honestly, features not yet implemented
• Your name and a link to the live version, if it is deployed

Issues, Actions and Pages

Issues are a discussion thread attached to your repository, one per bug, feature or task. Each gets a number, and that number is the glue across the whole platform: writing Fixes #12 in a commit message or a pull request description makes GitHub link them and close the issue automatically when the change reaches your default branch. For a four-person project this replaces the chat messages nobody can find two weeks later.

Actions runs commands automatically in response to events. You put a YAML file in .github/workflows/ describing what should happen — most commonly "when someone opens a pull request, install the dependencies and run the tests". The result appears as a green tick or a red cross on the pull request, so a broken change is caught before anyone merges it rather than during your demo.

Pages publishes a static site from a repository, at no cost, on a github.io address. For an HTML, CSS and JavaScript project this turns "here is my code" into "here is the working thing", which is a substantially better link to send. It serves static files only, so anything needing a server-side language or a database needs different hosting.

You do not need all of these on day one. Start with a repository, a good README and a habit of pushing. Add Issues when you are working with someone else, and Actions when you have tests worth running.

• Issues — numbered, searchable, and linkable from commits with Fixes #12
• Labels and milestones — group issues by bug, enhancement or by deadline
• Projects — a board view over your issues for planning
• Actions — automation defined by YAML files in .github/workflows/
• Pages — free static hosting straight from a branch or folder
• Releases — attach built files and release notes to a tagged version
• Stars and forks — how other people bookmark and copy your work