Using GitHub-hosted Projects¶

1. Before You Start¶

• Website: https://github.com
• Account: create a GitHub account if you do not already have one.
• Operating systems: Linux, Windows, and macOS are all supported.
• Tooling: Git.

This guide shows the common workflow for publishing an existing local project on GitHub.

2. Publishing a Local Project¶

Make sure your Git user name and email are configured before starting.

2.1 Create a local Git repository¶

Create the project locally, initialize Git, and make the first commit:

git init
# Create a README if the command is available; otherwise create it manually
touch README.md
git add .
git commit -m "first commit"

2.2 Configure an SSH key for GitHub¶

Git can use SSH encryption to communicate with GitHub. Generate a key pair for the current user:

mkdir ~/.ssh
ssh-keygen -t rsa -C "[email protected]"
# The public and private key files are created under ~/.ssh

Add the public key in GitHub:

Profile picture → Settings → SSH and GPG keys → New SSH key

Click Add SSH key and confirm your GitHub password if requested.

Then open the repository on GitHub and copy its SSH clone URL.

2.3 Connect the local and remote repositories¶

Add the remote repository to the local project:

git remote add origin [email protected]:zalebool/GitHub_test.git

If the remote repository already contains files and the local project should be the source of truth, push the local branch:

git push -u origin master

# Force-push only when you understand the impact on shared history
git push -u origin master --force

2.4 Pulling and pushing changes¶

A typical update sequence is:

git pull origin master
git add .
git commit -m "Describe the change"
git push origin master

3. Other Common GitHub Tasks¶

3.1 Adding a tag to a commit¶

# Tag the current commit
git tag v1.0.0

# Or tag a specific commit
git tag v1.0.0 <commit-hash>

Push all local tags:

git push origin --tags

Or push one tag only:

git push origin v1.0.0

3.2 Creating a release¶

First create and push the release tag:

git tag v1.0.0
git push origin v1.0.0

Then open Releases in the GitHub repository.

• Tag version: choose the tag created above.
• Release title: usually the version number.
• Description: describe new features, fixes, and known notes.
• Attach binaries: upload compiled binaries or installation packages when needed.

Click Publish release to finish.

4. Common Issues¶

Remote URL needs to be replaced¶

If the existing origin remote is incorrect:

git remote rm origin

Then add the correct remote URL again.

LF and CRLF warning on Windows¶

warning: LF will be replaced by CRLF in README.md.
The file will have its original line endings in your working directory

Windows commonly uses CRLF line endings, while Linux commonly uses LF. To convert to LF when committing and CRLF when checking out on Windows:

git config --global core.autocrlf true