Beyond Your Local Machine

So far, everything has been local. Your Git repository lives on your computer. This is powerful, but limited:

• What if your hard drive fails?
• How do you share code with collaborators?
• How do you work on multiple computers?
• How do you contribute to open source projects?

Remote repositories solve these problems. A remote is a copy of your repository hosted somewhere else, typically on a service like GitHub. You synchronize your local repository with the remote, giving you backup, sharing, and collaboration.

GitHub, GitLab, and Bitbucket

Several services host Git repositories:

GitHub: The most popular. Owned by Microsoft. Home to most open source projects.

GitLab: Strong DevOps features. Offers self-hosted option.

Bitbucket: Owned by Atlassian. Integrates with Jira.

This guide focuses on GitHub, but the Git commands work with any remote.

Creating a GitHub Account

If you don't have a GitHub account:

1. Go to github.com
2. Click "Sign up"
3. Choose a username (this will be in your profile URL)
4. Enter your email and create a password
5. Verify your email

Your GitHub username becomes part of your developer identity. Choose something professional or at least memorable.

Creating a Remote Repository

Two common scenarios: starting fresh or adding a remote to an existing project.

Scenario 1: New Repository on GitHub

1. Log into GitHub
2. Click "+" in the top right, then "New repository"
3. Enter a repository name (e.g., cpp-calculator)
4. Choose public or private visibility
5. Don't initialize with README (we'll push existing code)
6. Click "Create repository"

GitHub shows instructions for connecting your local repository. We'll cover these next.

Scenario 2: Existing Local Repository

If you already have a local Git repository:

# Add GitHub as a remote named "origin"
git remote add origin https://github.com/yourusername/cpp-calculator.git

# Verify the remote was added
git remote -v

Output:

origin  https://github.com/yourusername/cpp-calculator.git (fetch)
origin  https://github.com/yourusername/cpp-calculator.git (push)

Understanding "Origin"

"Origin" is a conventional name for your primary remote repository. It's not special to Git, just a widely-used convention.

You can have multiple remotes with different names, but origin typically refers to your main remote (usually your GitHub repository).

Pushing to GitHub

Send your local commits to the remote:

git push -u origin main

Breaking this down:

• git push: Send commits to a remote
• -u: Set up tracking (only needed the first time)
• origin: The remote to push to
• main: The branch to push

First push might ask for credentials. Enter your GitHub username and password (or personal access token, which we'll cover).

After the first push with -u, you can simply use:

git push

Git remembers the tracking relationship.

Personal Access Tokens

GitHub no longer accepts passwords for Git operations. You need a Personal Access Token (PAT):

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Give it a name (e.g., "Git CLI")
4. Select scopes (check repo for full repository access)
5. Click "Generate token"
6. Copy the token immediately (you won't see it again)

Use this token as your password when Git asks for credentials.

Store credentials so you don't have to enter them repeatedly:

# macOS
git config --global credential.helper osxkeychain

# Windows
git config --global credential.helper wincred

# Linux (temporary cache)
git config --global credential.helper cache

SSH Authentication (Alternative)

Instead of HTTPS and tokens, you can use SSH keys:

Generate SSH Key

ssh-keygen -t ed25519 -C "your.email@example.com"

Press Enter to accept the default location. Optionally set a passphrase.

Add Key to GitHub

1. Copy your public key:

   cat ~/.ssh/id_ed25519.pub
   

2. Go to GitHub → Settings → SSH and GPG keys → New SSH key
3. Paste the key and save

Use SSH URLs

When adding remotes, use SSH URLs:

git remote add origin git@github.com:yourusername/cpp-calculator.git

SSH is more convenient once set up since you don't need tokens.

Cloning Repositories

To download an existing repository:

git clone https://github.com/username/repository.git

This:

• Creates a new folder with the repository name
• Downloads all code and history
• Sets up origin automatically

For SSH:

git clone git@github.com:username/repository.git

Clone into a specific folder:

git clone https://github.com/username/repository.git my-folder-name

Fetching and Pulling

When the remote repository has changes you don't have locally:

Fetch

Download changes but don't apply them:

git fetch origin

This updates your knowledge of what's on the remote but doesn't change your working files. Safe to run anytime.

Pull

Download and apply changes:

git pull

This is essentially git fetch followed by git merge. It updates your local branch with remote changes.

If your local branch has diverged from the remote, pull might create a merge commit or ask you to resolve conflicts.

The Push/Pull Workflow

Basic workflow when working alone with GitHub:

# 1. Make sure you have latest changes
git pull

# 2. Do your work
# ... edit files ...

# 3. Commit your changes
git add .
git commit -m "Add new feature"

# 4. Push to GitHub
git push

Always pull before starting work to avoid conflicts.

Remote Branches

When you push a branch, it creates a corresponding branch on the remote:

git checkout -b feature/new-ui
# ... make commits ...
git push -u origin feature/new-ui

View all branches including remote ones:

git branch -a

Remote branches appear as remotes/origin/branch-name.

Keeping Branches Synchronized

Push a local branch to remote:

git push origin branch-name

Pull a remote branch that doesn't exist locally:

git checkout -b feature/remote-feature origin/feature/remote-feature

# Or simply
git checkout feature/remote-feature

Git automatically sets up tracking if a matching remote branch exists.

Delete a remote branch:

git push origin --delete branch-name

Collaborating with Others

When multiple people work on the same repository:

Fork and Pull Request Workflow

Common for open source contributions:

1. Fork: Create your own copy of someone else's repository on GitHub
2. Clone: Clone your fork locally
3. Branch: Create a feature branch
4. Commit: Make your changes
5. Push: Push to your fork
6. Pull Request: Ask the original repository to merge your changes

Creating a fork (on GitHub):

1. Go to the repository you want to contribute to
2. Click "Fork" in the top right
3. Clone your fork

git clone https://github.com/yourusername/forked-repo.git

Add the original repository as a remote:

git remote add upstream https://github.com/original-owner/repo.git

Now you have two remotes:

• origin: Your fork
• upstream: The original repository

Keep your fork updated:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Shared Repository Workflow

When you have direct access to a repository (team projects):

1. Clone the repository
2. Create a feature branch
3. Make commits
4. Push your branch
5. Create a Pull Request on GitHub
6. Team reviews and merges

This keeps the main branch stable while work happens on branches.

Pull Requests

A Pull Request (PR) is a GitHub feature (not part of Git itself) that lets you propose changes and discuss them before merging.

Creating a Pull Request

1. Push your branch to GitHub
2. Go to the repository on GitHub
3. GitHub often shows a prompt to create a PR for recent pushes
4. Or click "Pull requests" → "New pull request"
5. Select your branch
6. Write a description of your changes
7. Click "Create pull request"

PR Best Practices

Write a good description: Explain what changed and why.

Keep PRs focused: One feature or fix per PR is easier to review.

Reference issues: If fixing a bug, write "Fixes #123" to link the issue.

Respond to feedback: Reviewers may request changes. Discuss and update your PR.

Handling Conflicts with Remotes

If someone else changed the same files you changed:

git pull

CONFLICT (content): Merge conflict in main.cpp

Resolve conflicts the same way as with branches:

1. Open conflicted files
2. Edit to resolve the markers (<<<<<<<, =======, >>>>>>>)
3. git add the resolved files
4. git commit
5. git push

To avoid conflicts, communicate with teammates about who's working on what, and pull frequently.

README and Repository Documentation

GitHub displays a README.md file on the repository's main page. Include:

• Project description
• How to build and run the code
• Dependencies required
• Basic usage examples
• How to contribute

# My C++ Project

A brief description of what this project does.

## Building

```bash
mkdir build && cd build
cmake ..
make

Usage

./myprogram input.txt

License

MIT License

## .gitignore for GitHub

Make sure your `.gitignore` prevents uploading:
- Compiled binaries
- Build artifacts
- IDE settings
- Sensitive information (API keys, passwords)

Example for C++:

Compiled files

*.o *.obj *.exe *.out

Build directories

build/ cmake-build-*/

IDE files

.vscode/ .idea/ *.swp

OS files

.DS_Store Thumbs.db

Never commit secrets. If you accidentally commit a password or API key, consider it compromised and rotate it immediately.

## HelloC++ Git Integration

Now that you understand GitHub and remotes, you're ready to use HelloC++'s [Git integration](/blog/using-git-integration) for guided projects.

The workflow is similar:

1. Clone your personal project repository
2. Make changes locally in your IDE
3. Commit and push
4. HelloC++ automatically builds and tests your code

The difference is that HelloC++'s build system provides automated feedback instead of just storing your code.

## Practice Exercises

1. **Create a GitHub repository** for a simple C++ project
2. **Push existing code** from a local repository to GitHub
3. **Clone a public repository** (any C++ project you find interesting)
4. **Create a branch**, make changes, push, and create a pull request (even to your own repository, you can merge it yourself)
5. **Fork a repository** and explore how upstream remotes work

## What's Next

You now have the complete Git fundamentals:

- [What is Version Control](/blog/what-is-version-control) - Concepts and mental models
- [Installing Git](/blog/installing-git) - Setup and configuration
- [Your First Repository](/blog/your-first-git-repository) - Basic workflow
- [Understanding Commits](/blog/understanding-git-commits) - History and snapshots
- [Branches and Merging](/blog/git-branches-and-merging) - Parallel development
- Working with GitHub - Remote collaboration (this article)

With these skills, you can:
- Track any project with version control
- Collaborate with other developers
- Contribute to open source
- Use HelloC++'s [Git integration](/blog/using-git-integration)

Git has more advanced features (rebasing, cherry-picking, bisecting), but these fundamentals cover the vast majority of daily use. Master these first, then explore advanced topics as you encounter needs.

**Ready to put Git to work?** Try our [guided projects](/projects) with local development mode. Use your favorite IDE, push your changes, and let HelloC++ handle the builds.

**Part of the [Git Fundamentals](/blog/git-fundamentals) series.**

[Branches and Merging](/blog/git-branches-and-merging) | [Using Git Integration](/blog/using-git-integration)