Skip to content

09-troubleshooting.md

Latest commit

 

History

History
131 lines (95 loc) · 3.33 KB

09-troubleshooting.md

File metadata and controls

131 lines (95 loc) · 3.33 KB

🩹 Troubleshooting

<- Previous: Branches, Forks, Origin, And Upstream Next: Final Evaluation ->

🎯 Outcome

Diagnose common Git, SSH, signing, and remote problems without guessing.

✅ You Should Be Able To

  • decide whether a problem is about installation, authentication, signing, or remotes
  • run a short triage checklist before changing settings
  • apply a targeted fix instead of repeating setup steps blindly

🧰 Quick Triage Checklist

Run these commands first:

git --version
git config --global --list
ssh-add -l
git remote -v
bash scripts/run-full-check.sh

On Windows PowerShell, replace the last command with:

powershell -ExecutionPolicy Bypass -File scripts/run-full-check.ps1

On Windows Command Prompt, use:

scripts\run-full-check.cmd

These checks usually tell you whether the problem is local Git configuration, SSH authentication, or remote configuration.

🚨 Problem: git: command not found

Git is not installed or is not available on your shell PATH.

Fix:

  1. install Git again for your operating system
  2. open a new terminal session
  3. run git --version

🔐 Problem: Permission denied (publickey)

GitHub rejected the SSH connection. This is an authentication problem.

Fix:

  1. check whether the key is loaded:
ssh-add -l
  1. if needed, start ssh-agent and load the key again:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
  1. confirm that the public key in ~/.ssh/id_ed25519.pub is registered in GitHub as an Authentication Key
  2. test again:
ssh -T git@github.com

🖋️ Problem: Commit shows Unverified on GitHub

This is a signing problem, not an authentication problem.

Check:

  1. the commit was created after signing was enabled
  2. user.email matches an email associated with your GitHub account
  3. the public key was also added to GitHub as a Signing Key
  4. these settings exist:
git config --global --get gpg.format
git config --global --get user.signingkey
git config --global --get commit.gpgsign

If the commit was created before signing was enabled, create a new signed commit.

🌐 Problem: Push asks for a password or token

Your remote is probably using HTTPS instead of SSH.

Check:

git remote -v

If the remote starts with https://github.com/, switch it to SSH:

git remote set-url origin git@github.com:username/repo.git

In this course, origin should usually point to your own copy of the template repository.

🌿 Problem: src refspec main does not match any

This usually means you do not have a commit on the branch yet, or you are pushing the wrong branch name.

Fix:

  1. check the current branch:
git branch --show-current
  1. create a commit if the repository is still empty
  2. push the current branch explicitly:
git push -u origin <branch-name>

🏁 Success Criteria

  • You can tell whether a failure is about auth, signing, or remote URLs.
  • You can explain why Permission denied (publickey) and Unverified are different problems.
  • You know which commands to run before changing your setup.
<- Previous: Branches, Forks, Origin, And Upstream Next: Final Evaluation ->