Introduction
One of the first things I wanted to learn after creating my projects was how to actually put them online. I had a project sitting on my computer, but getting it online was a completely different story.
I knew that developers used GitHub to store their code, but the commands I was taught were new to me. Words like SSH made the process look more complicated than it really was. I later realized that the difficult part was not really the commands, but understanding what each step was doing.
This is the route I followed: set up Git on my Mac, connect it to GitHub with SSH, turn the project folder into a repository and push the project online.
1. GitHub First
I needed a place to store my project online, so the first step was creating a GitHub account.
You can create an account on GitHub if you do not already have one.
After signing up and verifying my email address, I created a new repository. A repository, or repo, is where GitHub stores a project and its Git history.
For example, if my project is called my-first-web, I can create a repository with the same name.
Since I already have the project on my Mac, I will create the repository without adding any files to it for now. This will allow me to connect my local project to the GitHub repository later.
2. Checking for Git on macOS
The first thing I checked was whether Git was already installed on my Mac.
I opened the Terminal application on my Mac. I can find it by pressing Command + Space, searching for Terminal, and opening it.
Then I run:
git --version
If I get a version number, it means Git is already available on my Mac.
3. Telling Git Who I Am
Git needs a name and email address for the commits it creates. I set both values in Terminal.
In Terminal, I run:
git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"
To make sure the information was saved correctly, I can check my name and email with:
git config --global user.name
git config --global user.email
If both commands return the information I entered, then Git is configured correctly.
4. Choosing the Initial Branch
After configuring my name and email, I wanted to make sure Git would use main as the default branch when I created a new repository.
I can set this by running the following command in Terminal:
git config --global init.defaultBranch main
From then on, a new git init uses main as its initial branch. The init.defaultBranch configuration controls the default branch name for newly initialized repositories.[1]
I can check that the setting was saved by running:
git config --global init.defaultBranch
If everything is correct, Terminal should show:
main
5. A Quick Configuration Check
Before continuing, I wanted to make sure that the settings I entered earlier were actually saved.
I can check my Git username with:
git config --global user.name
I can check my email with:
git config --global user.email
I can also see all of my global Git settings by running:
git config --global --list
This is a quick way to confirm the settings. I would not post the output publicly if it includes an email address or another private value.
6. Getting SSH Ready
SSH is what lets my Mac authenticate with GitHub when I work with the repository.
SSH stands for Secure Shell. I use it to authenticate my computer with GitHub when working with my repositories. With SSH authentication, GitHub uses my local private key and the public key added to my account instead of asking me to enter my username and personal access token for every Git operation.[2]
I checked for an existing key before creating another one.
In Terminal, I run:
ls -al ~/.ssh
If I already have an SSH key, I may see files such as:
id_ed25519
id_ed25519.pub
The file ending in .pub is my public key, while the file without .pub is my private key.
The public key can be added to GitHub, but the private key should stay on my computer. I should never share my private key with anyone.
7. Making a Key If I Need One
If I do not already have an SSH key, I can create one using:
ssh-keygen -t ed25519 -C "your-email@example.com"
I should replace the email address with the email I use for my GitHub account.
For example:
ssh-keygen -t ed25519 -C "myemail@example.com"
After running the command, Terminal will ask where I want to save the key. I can press Enter to accept the suggested location.
It will also ask me whether I want to create a passphrase. A passphrase provides additional protection for my SSH key, so I can create one if I want.
After creating the key, I can check that it exists by running:
ls -al ~/.ssh
I should now see something similar to:
id_ed25519
id_ed25519.pub
8. Loading the Key into macOS
After creating the SSH key, I need to add it to the SSH agent on my Mac.
First, I start the SSH agent:
eval "$(ssh-agent -s)"
Then I add my private key:
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
The --apple-use-keychain option allows macOS to use the Apple Keychain when working with my SSH key.
If the key is added successfully, Terminal should show a message confirming that the identity has been added.
9. Copying the Public Key
Now I need to copy my public SSH key so that I can add it to GitHub.
Since I am using a Mac, I can copy the key directly to my clipboard by running:
pbcopy < ~/.ssh/id_ed25519.pub
I can also display the key in Terminal with:
cat ~/.ssh/id_ed25519.pub
The output will look similar to:
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... myemail@example.com
I need to copy the complete line if I choose to copy it manually.
The important thing is that I only use the public key. I should never copy or upload my private key.
10. Adding It to GitHub
After copying my public SSH key, I can add it to my GitHub account. GitHub’s current instructions require the public key to be added to the account before the key can be used for SSH access.[3]
I go to GitHub and:
- Sign in to my account.
- Click my profile picture.
- Select Settings.
- Open SSH and GPG keys.
- Click New SSH key or Add SSH key.
- Give the key a name, such as My Mac.
- Paste my public key into the key field.
- Click Add SSH key.
The public key is now associated with my GitHub account.
11. Checking the Connection
I tested the connection before attempting the first upload.
In Terminal, I run:
ssh -T git@github.com
The first time I run this command, GitHub may ask me to confirm that I want to continue connecting. I should verify the host fingerprint before accepting it.[4]
If everything is configured correctly, I should receive a message similar to:
Hi YOUR_USERNAME! You've successfully authenticated, but GitHub does not provide shell access.
This means GitHub has successfully recognized my SSH key.
I can think of the connection like this:
My Mac
↓
SSH private key
↓
GitHub checks the public key
↓
Authentication successful
If I get the successful authentication message, I know that the SSH setup is working.
12. Moving into the Project
With the setup complete, I moved into the project I wanted to upload.
I open Terminal and use cd to move into my project folder.
For example:
cd path/to/my-project
If I am not sure which folder I am currently in, I can check with:
pwd
I can also see the files inside the current folder by running:
ls
This is useful because I want to make sure I am working inside the correct project before running Git commands.
13. Turning the Folder into a Repository
My project is currently just a normal folder on my Mac.
To start tracking it with Git, I need to initialize a Git repository. The git init command creates the repository’s .git directory and the data Git needs to track the project’s history.[1]
Inside the project folder, I run:
git init
This creates a hidden .git directory inside my project.
The .git directory contains the information Git needs to track my project and keep a history of the changes I make.
After running git init, I can check the current state of the project using:
git status
Git should show me the files that are currently not being tracked.
14. Adding a README
I also want my project to have a README file.
A README.md file is useful because it gives information about my project when anyone visit the repository on GitHub.
I can create a file called README.md and start with a simple description such as:
# My First Project
This is a project I created while learning and practicing Git and GitHub.
As I continue working on the project, I can add more information to the README, such as what the project does, how to install it, and how to use it.
15. Staging the Files
Once my project is ready, I need to tell Git which files I want it to track.
I run:
git add .
The . means that I am adding the files from the current project directory.
After adding the files, I can check the status again:
git status
The files should now appear as files that are ready to be committed.
This helped me understand that git add does not upload anything to GitHub. It simply prepares the changes for the next step.[5]
16. Making the First Commit
Once the files were staged, I made the first commit.
I run:
git commit -m "Initial commit"
I think of a commit as a saved checkpoint of my project.
The message after -m describes what I have saved. Since this is my first saved version, Initial commit is a suitable message.
For later changes, I can use messages that describe what I actually changed. For example:
git commit -m "Add project documentation"
This makes the project history easier to understand.
17. Linking the Remote
At this point, I have my project on my Mac and a repository on GitHub, but they are still separate.
I now need to connect the local project to the GitHub repository.
On my GitHub repository page, I copy the SSH repository address. It should look similar to:
git@github.com:your-username/your-repository.git
I then return to Terminal and run:
git remote add origin git@github.com:your-username/your-repository.git
Here, origin is the name Git uses for the remote repository.
I can check that the connection was added correctly with:
git remote -v
If everything is correct, I should see my GitHub repository listed as the remote.
18. Pushing to GitHub
Now I am ready to upload my project to GitHub.
First, I make sure that my branch is called main:
git branch -M main
Then I push my project to GitHub:
git push -u origin main
The push command sends my committed changes from my Mac to the GitHub repository. The -u option connects my local main branch with the remote main branch.[6]
After this first push, I can normally use:
git push
for future updates.
Once the command finishes, I can open my GitHub repository in the browser and refresh the page. My project files should now be visible on GitHub.
Seeing the files appear in the repository was the point where the whole workflow finally clicked for me.
19. What Future Updates Look Like
Uploading my project to GitHub once does not mean I am finished using Git.
As I continue working on the project, I will probably add files, change existing code or fix problems. Whenever I make changes, I need to save those changes with Git and then send them to GitHub.
The basic workflow is:
git add .
git commit -m "Describe my changes"
git push
For example, if I add a new page to my project, I could run:
git add .
git commit -m "Add new page"
git push
The commit creates a new checkpoint in my project’s history, while git push sends the changes to GitHub.
20. A Few Problems I Could Run Into
Errors are part of the process. I start by reading the message and checking the repository state instead of guessing at the cause.
SSH Permission Error
One common error is:
Permission denied (publickey)
If I get this error, I can test my SSH connection again:
ssh -T git@github.com
I can also check whether my SSH key is currently loaded:
ssh-add -l
If my key is not listed, I can add it again:
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
Wrong Repository Address
If my project is connected to the wrong GitHub repository, I can check the current remote address with:
git remote -v
If I need to change the repository address, I can use:
git remote set-url origin git@github.com:your-username/your-repository.git
I can then check the remote again:
git remote -v
My Files Are Not Showing on GitHub
If I make changes but do not see them on GitHub, I can first check the repository status:
git status
If Git shows that I have changes that have not been committed, I can run:
git add .
git commit -m "Update project"
git push
After refreshing the GitHub repository, the changes should appear.
The Short Version
After going through the complete setup, I realized that I would not need all of the commands every time I worked on a project.
For the first upload, the main workflow is:
git init
git add .
git commit -m "Initial commit"
git remote add origin git@github.com:your-username/your-repository.git
git branch -M main
git push -u origin main
Once the project is already connected to GitHub, the process becomes much shorter:
git add .
git commit -m "Describe my changes"
git push
Conclusion
After actually going through the process, I realized that understanding what each command does is more useful than simply memorizing them.
Git helps me keep track of changes in my projects, GitHub gives me a place to store and share those projects online, and SSH provides a secure way for my Mac to communicate with GitHub.
