Welcome, intrepid coder, to the world of Git and GitHub! This guide cuts through the noise to give you a solid understanding of version control, focusing on the practical steps and common pitfalls encountered in daily development. We’ll demystify local Git versus online platforms, walk through essential commands, and tackle the ever-present authentication headaches with solutions drawn from real-world scenarios.

Changelog

1. Git vs. GitHub: A Tale of Two Systems

Understanding the distinction between Git (the tool) and GitHub (the service) is foundational.

Local Git

Git is a version control system that lives on your computer. It meticulously tracks the history of your project as a series of commits.

• Repository (Repo): This is your project folder, distinguished by a hidden .git/ directory.
• Commit: A “snapshot” of your changes at a specific point in time.
• Branch: An independent line of development (e.g., main, feature/my-new-thing).
• Remote: A counterpart of your local repository hosted on a server (e.g., GitHub).

GitHub.com

GitHub is a hosting service built around Git repositories. It offers a suite of tools for collaborative development:

• Stores repositories online (publicly or privately).
• Facilitates collaboration through Pull Requests, Issues, and Code Reviews.
• Provides Continuous Integration/Continuous Deployment (CI/CD) with GitHub Actions.
• Can host container images and packages (e.g., GitHub Container Registry (GHCR): ghcr.io/...).

2. Open-Source Alternatives to GitHub

If you prefer self-hosting or exploring other platforms, these are excellent alternatives that all speak the same Git language:

• GitLab CE/EE: GitLab Community Edition is fully open-source, offering a comprehensive suite of DevOps tools.
• Gitea: A lightweight, self-hostable Git service, popular for its ease of deployment and minimal resource footprint.
• Forgejo: A community-driven fork of Gitea, focused on open governance.
• SourceHut: A minimalist, “Git-first” development platform.

3. The Typical Workflow: Six Key Concepts & Visualized

To master Git, grasp these six core areas, and visualize their flow.

• Working Tree: The actual files in your project directory, including any uncommitted changes.
• Staging Area / Index: A temporary area where you select which changes will be included in your next commit.
• Commit History: The chronological record of all your project’s commits.
• Branch: The current line of development you are working on.
• Remote origin: The URL pointing to your online repository (often called origin by default).
• Push/Pull: The actions of sending (pushing) or receiving (pulling) changes between your local repository and the remote.

Visualizing the Workflow

A simple mental model helps understand the core Git flow:

Working Directory (Your files)
        ↓ (`git add`)
Staging Area (Index)
        ↓ (`git commit`)
Local Repository (Commit history)
        ↓ (`git push`)
Remote Repository ([GitHub](https://github.com/), [GitLab](https://about.gitlab.com/), etc.)
        ↓ (`git pull`)
(Back to Working Directory for others)

4. Initial Setup: A Clean Start

Setting up Git correctly from the beginning prevents many headaches.

4.1. Set Your Git Identity (For Commits)

These details define the author of your commits; they are not your login credentials for GitHub. The user.name and user.email you set here are what will appear in the commit history on platforms like GitHub.

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

How to Check Your Current Git Identity

To see what user.name and user.email are currently set for your active repository or globally:

For the current repository:

git config user.name
git config user.email

Globally (for all repositories):

git config --global user.name
git config --global user.email

How to Change Your Git Identity

To change your Git identity:

Globally (recommended for most users, applies to all new repos):

git config --global user.name "Your New Name"
git config --global user.email "your-new-email@domain.tld"

For only the current repository (overrides global settings for this repo):

git config user.name "Project Specific Name"
git config user.email "project-email@domain.tld"

4.2. Initialize or Clone a Repository

There are two main ways to start:

• Clone an existing repository: This is standard for team projects or contributing to open source.

  # Using HTTPS
  git clone https://github.com/ORG/REPO.git
  # Using SSH
  git clone git@github.com:ORG/REPO.git

• Initialize a brand-new project: If you’re starting a project from scratch on your local machine.

  mkdir my-new-project
  cd my-new-project
  git init

  You can then connect it to a remote repository later once you create one online.

4.3. Check Your Remotes

Confirm the remote repository is correctly configured:

git remote -v

5. Essential Commands: Your Daily Toolkit

Here are the most frequently used Git commands and their purposes.

Status & Overview

git status
git log --oneline --decorate -n 20
git diff

Stage Files (Prepare for Commit)

git add .
# Or stage specific files:
git add path/to/file

Create a Commit

git commit -m "Brief, descriptive message"

Push / Pull Explained

• git push: Sends your local commits to the remote repository.
• git pull: Fetches changes from the remote and then merges them into your current local branch.

git push
git pull # = git fetch + git merge

Branching (Typical Workflow)

git checkout -b feature/my-new-feature
git push -u origin feature/my-new-feature

Mini-Example: Your First Commit!

Let’s try a complete cycle:

# 1. Create a new directory and initialize Git
mkdir my-first-repo
cd my-first-repo
git init

# 2. Create a file
echo "Hello, Git World!" > index.html

# 3. Check status (it's untracked)
git status

# 4. Stage the file
git add index.html

# 5. Check status again (it's staged)
git status

# 6. Commit the file
git commit -m "Add initial homepage with Hello World"

# 7. Check log (see your commit)
git log --oneline

# At this point, you'd typically connect to a remote and push.
# For now, you have a local commit!

6. Ignoring Files with .gitignore

Not every file belongs in your repository. Temporary files, build artifacts, and sensitive data should be ignored.

Why is node_modules (or target/) in my Git?!

This is a common beginner question. Files generated by your build system (like node_modules for JavaScript or target/ for Rust) should not be committed. They bloat your repository and cause unnecessary merge conflicts.

How to Use .gitignore

Create a file named .gitignore in the root of your repository and list the files or directories you want Git to ignore.

# Example .gitignore content
# Node.js dependencies
node_modules/

# Logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# OS generated files
.DS_Store
.env

# Build artifacts (e.g., for Rust)
target/

# Your application's local settings (if applicable)
config/local.yaml

# To create and add to .gitignore:
echo "node_modules/" >> .gitignore
echo "*.log" >> .gitignore
git add .gitignore
git commit -m "Add .gitignore to exclude common temporary files"

7. Crucial Context: Accounts vs. Repository Permissions

This is where many newcomers (and even seasoned pros) stumble.

GitHub Account (Personal) vs. Company/Organization Repository

On GitHub, repositories are often owned by an Organization (e.g., DELIGHTFUL-corp/my-project).

• You log in with a GitHub User Account (which might be your personal one).
• This user account needs permissions (e.g., WRITE, MAINTAIN, ADMIN) within the Organization’s repository.
• Without sufficient permissions, you might be able to read the repository but not push changes.

Common Pitfall: The Identity Crisis

Symptom: Your git push fails, even though you “know” you have access to the repository. The error message is often misleading (fatal: repository 'https://github.com/ORG/REPO.git/' not found) rather than an explicit “permission denied.” GitHub frequently returns a 404 (“not found”) for private repositories when permissions are lacking, to avoid leaking the existence of private repos.

8. Authentication: HTTPS vs. SSH (And Why Your Error Happened)

Authentication methods can be a source of confusion.

HTTPS (Token/Credentials)

With HTTPS, Git requires authentication details. While passwords were used in the past, today it’s almost always:

• A Personal Access Token (PAT), or
• The GitHub CLI (gh) managing a token for you automatically. The GitHub CLI is an optional but highly recommended tool for smoother authentication workflows.

Installing GitHub CLI

Debian/Ubuntu:

sudo apt update
sudo apt install gh

Arch Linux:

sudo pacman -S github-cli

Your specific stumbling block was classic:

• gh repo view ... viewerPermission correctly showed ADMIN (meaning permissions were there).
• But git ls-remote origin HEAD reported Repository not found.
• This often happens when Git uses incorrect or cached credentials.

The Fix (from your real-world case)

gh auth login
gh auth setup-git

This sequence ensures that Git is configured to use the credentials managed by the GitHub CLI for https://github.com/... remotes.

SSH (Keys)

SSH is often more “set it and forget it” once correctly configured:

• You add an SSH public key to your GitHub account.
• Your remote URL will look like git@github.com:ORG/REPO.git.
• SSH authentication is handled by your SSH agent, not Git’s credential storage. This setup avoids credential helper conflicts, making it robust for many users.

9. Troubleshooting Checklist: When git push Acts Up

If git push fails, go through this checklist.

9.1. Is the Remote Correct?

git remote -v

9.2. Can You Even “See” the Repository? (Authenticating Access)

git ls-remote origin HEAD

If this command fails with “repository not found” or “authentication failed,” the issue is almost certainly authentication, the remote URL, or your permissions. This is the first diagnostic step for “git push repository not found” problems.

9.3. Which GitHub Identity is Active (GH CLI)?

gh auth status

9.4. What Permissions Do You Have?

gh repo view ORG/REPO --json viewerPermission

9.5. If HTTPS Credentials are Stuck: Re-link

gh auth setup-git

9.6. Clear Cached Credentials (If Necessary)

printf "protocol=https\nhost=github.com\n\n" | git credential reject

10. Your Minimal Daily Workflow

Once authentication is set up correctly (as it should be now), your daily routine is simple:

# 1. Start by pulling any remote changes (optional, but good practice)
git pull

# 2. Check what you've modified
git status

# 3. Stage your changes
git add .

# 4. Commit your changes
git commit -m "Description of your changes"

# 5. Push your changes to the remote repository
git push

11. Practical Rules: Keeping it Clean Long-Term

Adhere to these rules for a smoother Git experience.

• One Identity Per Purpose:
  • GitHub Account (login) = Access & Permissions.
  • Git user.name/user.email = Commit Author (can be your company identity).
• For Private/Org Repos: Always ensure your GitHub user is explicitly part of the Organization’s team with the necessary permissions.
• When Switching Accounts: After changing GitHub accounts (e.g., personal to work), always run gh auth status and potentially gh auth setup-git again. This is key to resolving “git authentication failed” issues.
• When it says “Repository not found”: First, check git ls-remote origin HEAD. If that fails, it’s time to check your credentials and active account. This specific error often means your authentication is failing for “github 404 private repository” scenarios.

12. Managing Multiple Git Identities (e.g., Work vs. Personal)

It’s common to work on different projects that require different Git identities (e.g., a work email/name for company projects and a personal one for open-source contributions). Git offers flexible ways to manage this.

Git applies configurations in a specific order:

1. Repository-specific (.git/config): These settings override all others for the current repository.
2. Global (~/.gitconfig): These settings apply to all repositories that don’t have their own specific configuration.
3. System-wide ($(prefix)/etc/gitconfig): Least specific, rarely modified directly.

Option A (Simple): Set Identity Per Repository

The easiest way to use different identities is to set them directly within each project’s folder. This overrides your global settings only for that specific repository.

1. Set your default global identity (e.g., your personal one, or the one you use most often):

   git config --global user.name "Your Default Name"
   git config --global user.email "your-default@mail.tld"

2. Navigate to a specific project folder (e.g., a work project).
3. Set the identity for only this repository:

   git config user.name "Work Name"
   git config user.email "work@company.com"

   This creates/modifies the .git/config file in that repository.

To verify the local settings:

git config --local user.name
git config --local user.email

Option B (Advanced): Conditional Includes for Directories

If you organize your projects into separate top-level directories (e.g., ~/work/company-projects/ and ~/personal-projects/), you can use Git’s includeIf directive. This automatically applies different configurations based on the path of the repository.

1. Define your default global identity in ~/.gitconfig (e.g., your personal one):

   # ~/.gitconfig
   [user]
     name = Dude (Personal)
     email = dude.personal@mail.tld
   
   [includeIf "gitdir:~/work/delightful/"]
     path = ~/.gitconfig-delightful
   
   [includeIf "gitdir:~/personal-projects/"]
     path = ~/.gitconfig-personal

   Note: The gitdir: path should end with a / to indicate a directory. Make sure these paths exist on your system.

2. Create separate configuration files for each specific context.

   ~/.gitconfig-delightful:

   [user]
     name = DELIGHTFUL Inc.
     email = dude.work@delightful.tld

   ~/.gitconfig-personal:

   [user]
     name = Dude (Open Source)
     email = dude.opensource@mail.tld

Now, when you enter a repository within ~/work/delightful/, Git will automatically use the DELIGHTFUL Inc. identity. When you’re in ~/personal-projects/, it will use Dude (Open Source). Any other repository will fall back to the default Dude (Personal).

What if You Use Multiple GitHub Accounts (not just identities)?

If you manage entirely separate GitHub accounts (e.g., github.com/my-personal-account and github.com/my-work-account), you’ll also need to configure separate SSH keys and SSH host aliases in your ~/.ssh/config file. This tells Git which SSH key to use when connecting to github.com for specific projects. This setup is more advanced and beyond the scope of this beginner tutorial, but it’s important to be aware of it.

Conclusion

You’re now equipped with the knowledge to navigate Git and GitHub with confidence! We’ve covered the fundamentals, delved into the crucial authentication challenges, and provided a clear path to troubleshooting common issues like “git push repository not found.” Understanding how to manage your Git identity, especially across multiple projects, will streamline your workflow significantly. Version control can seem daunting, but with these principles and tools, you’ll be committing and collaborating like a pro in no time.

📚OFFICIAL GIT DOCUMENTATION 📦GITHUB DOCUMENTATION