What you’ll build

A new repository on GitHub with an initial README.md and a first commit pushed from your computer.

---

Prerequisites (quick checklist)

• A GitHub account (signup at github.com).

• Git installed locally (check with git --version).

• A terminal (macOS/Linux) or Git Bash (Windows).

• An editor (VS Code, Notepad++, etc.).

• Optional but recommended: know your GitHub username and email.

---

1. Quick overview (two paths)

You can create a repo:

1. On the GitHub website and then clone it locally.

2. Or create locally with git init and push it to GitHub.
   Both are covered below.

---

2. Create a repository on GitHub (website)

1. Sign in to GitHub (github.com).

   • 

• 

2. Click the + icon (top-right) → New repository.

   

   

3. Fill the Repository name (e.g., my-first-repo).

   • Optionally add a short Description.

   • Choose Public (anyone can see) or Private (only you/collaborators).

   • Initialize this repository with: check Add a README file (recommended for first repo).

   • Optional: add a .gitignore and License from the dropdowns.

     

4. Click Create repository. You’ll be taken to the repo page (URL like github.com/your-username/my-first-repo).

   • 

---

3. Work with your repo from your computer (command-line)

Assuming you created the repo on the website and want to clone it locally.

A. Clone the repo

• Copy the HTTPS or SSH clone URL from the green Code button on your repo page.

• In your terminal run (HTTPS example):

cd ~/projects
git clone https://github.com/your-username/my-first-repo.git
cd my-first-repo

• Or SSH:

git clone git@github.com:your-username/my-first-repo.git
cd my-first-repo

B. Create or edit files

• Create a file and open it in your editor:

echo "# My First Repo" > README.md
code README.md   # or use any editor

C. Stage, commit, push

git add README.md
git commit -m "Add README with project title"
# ensure local branch is named main (GitHub default)
git branch -M main
git push -u origin main

If you get an authentication prompt:

• For HTTPS: use your Personal Access Token (PAT) as password (GitHub no longer accepts plain passwords).

• For SSH: ensure your SSH public key is added to GitHub (Settings → SSH and GPG keys).

---

4. Create a repo locally and push to GitHub (alternative)

If you didn’t create the repo on GitHub first:

1. Create the project folder:

mkdir my-first-repo
cd my-first-repo
git init
echo "# My First Repo" > README.md
git add .
git commit -m "Initial commit"

2. Create an empty repo on GitHub website (name my-first-repo) without initializing README (so it’s empty). Copy its remote URL.

3. Add remote and push:

git branch -M main
git remote add origin https://github.com/your-username/my-first-repo.git
git push -u origin main

---

5. Optional: GitHub CLI (fast workflow)

If you have gh (GitHub CLI) installed:

gh auth login            # follow prompts to connect your GitHub account
gh repo create my-first-repo --public --source=. --remote=origin --push

This creates and pushes the repo in one step.

---

6. Common mistakes & quick fixes

• Forgot to initialize README on GitHub but created a local repo
  Fix: If both sides have commits, run git pull --rebase origin main before pushing, or create remote first then push.

• Push rejected: failed to push some refs
  Usually because remote has commits you don’t. Fix:

    git pull --rebase origin main
    # or if you want to merge:
    git pull origin main
    git push
  

• Local branch named master but GitHub expects main
  Fix:

    git branch -M main
    git push -u origin main
  

• Permission denied (publickey)
  You’re using SSH but no key is set up. Create one:

    ssh-keygen -t ed25519 -C "your_email@example.com"
    eval "$(ssh-agent -s)"
    ssh-add ~/.ssh/id_ed25519
    # then copy the contents of ~/.ssh/id_ed25519.pub and add in GitHub Settings → SSH and GPG keys
  

• HTTPS prompts for password (and fails)
  GitHub requires a Personal Access Token (PAT). Generate a PAT in GitHub Settings → Developer settings → Personal access tokens, then use it as the password when prompted.

• Accidentally committed secrets (API keys, passwords)
  Remove them from history and rotate the secret. Tools: git filter-repo or BFG Repo-Cleaner. After rewriting history, force-push and rotate keys immediately.

• Large files (>100 MB) blocked
  Use Git LFS for large files or store assets elsewhere.

• Wrong user name/email on commits
  Configure Git globally:

    git config --global user.name "Your Name"
    git config --global user.email "you@example.com"
  

---

7. Short README example (copy & paste)

# My First Repo

This is my first GitHub repository.  
## What’s inside
- README with project description
- First commit pushed from local machine

---

8. Next steps & tips

• Add a useful README with how to run the project.

• Learn branches: git checkout -b feature-1.

• Use Issues and Pull Requests to manage changes.

• Explore Actions for CI/CD once comfortable.

---

Conclusion

You just created your first GitHub repository and learned how to clone, commit, and push changes.