I decided to migrate to GitHub for my source code repository. Previously, I was using Subversion with a repository on my own unmanaged VPS (Virtual Private Server). I used my own Subversion installation because in the past (prior to January 2019), GitHub’s free personal user account did not allow private repositories and I did not want to expose my source code to the general public.
Because GitHub now allows unlimited private repositories for the free user account, I decided to offload source code management to it. GitHub will also allow me to share my code with others or the general public in the future.
Create GitHub User Account
Creating a GitHub personal user account is easy, except for the need to prove that you are human. You’ll need to go through the CAPTCHA process when signing up. The default was 10 visual puzzles. The problem was I couldn’t figure out how to solve those visual puzzles. It asked me to find the glass with the most liquid containing the icon matching the requested icon, but after scrolling through a dozen images, there was no suitable match!
Thankfully, I was able to switch to 10 audio puzzles. The audio puzzles were easier and consisted of identifying the odd animal sound out of three. (GitHub seemed to love cat noises.)
I found comments online about people having to do 20 puzzles; I guess they are twice as inhuman as I am.
Note: When signing up, you will be offered the option to “Continue with Google” or “Continue with Apple” to use your Google or Apple account to log into GitHub. I chose to use a standalone username and password because I don’t want Google or Apple to know more than they need to. And if something goes wrong with Google or Apple 3rd party authentication, I don’t want to be locked out of other websites. I do use a password manager and try to use a different password for each website though. If you are using the same password for every website, it would be best to use Google or Apple account because it would reduce the number of times you have to input that password (reduce exposure).
Organize Repositories
Because I am managing a few source code projects which belong to a friend, I wanted to group and separate them from my own projects. I was looking for some feature like a project hierarchy tree, but GitHub does not support anything like that. GitHub’s only feature that supports grouping repositories is an organization. (I consider my own user account as the default virtual “organization”.)
The organization feature is not very visible. To create an organization, you have to open the user navigation menu (by clicking on the top-right user icon) and selecting “Organizations”. Click on the “New organization” button and select the “Create a free organization” option. Fill in the necessary information and follow instructions to create your new organization.
To switch between your user account and the newly created organization, you can click on the new organization name listed under the “Organizations” section in the same page. Or if you are in the default main “Dashboard” page, you can click on the top-left username link and select a different organization from the drop-down menu. (There are other methods to switch the organization including links to organization-specific repositories or an organization icon which show up in the left panel depending upon which page you are on.)
Create a Repository
I created the repositories using the GitHub web interface because I needed to ensure that they were created under my user account or under my friend’s organization. (I don’t know how to specify the user account or organization when creating a repository using the Git command line.) Creating the repository requires you to go the Repositories page by clicking on top-right user icon and selecting “Repositories”. Then click on the New button to create a repository.
When configuring the new repository, I recommend adding the README file. Also, add the “.gitignore” file if you plan to have files which you do not wish to check into the repository. There was a bit of confusion because it required me to select a “.gitignore template”. For my PHP project, I searched for “PHP” and selected “CakePHP”. Basically, the template will pre-fill the “.gitignore” file with entries. In this case, the template had entries for temporary files generated by the CakePHP framework. I plan to replace the “.gitignore” file contents with my own file selections when needed. (Alternatively, you can manually check in a “.gitignore” file at any time.)
Use GitHub with SSH
Rather than inputting my GitHub username and password when using the Git command line, I prefer to use SSH (Secure Shell) client with public/private key authentication. Configuring username and password on the Git command line would expose them when you show the Git configuration settings.
To use SSH with GitHub, follow instructions at Configure SSH Client and Key-Based Authentication (on macOS and Linux) to create your client public key file (named “id_rsa.pub”).
Add the public key to GitHub using the web interface:
- Click on the top-right user icon and select Settings.
- Click on “SSH and GPG keys” section.
- Click on “New SSH key” button
- If you do not input Title, the Title will be populated with the comment (email address) in the public key file.
- Paste the contents of the public key file (“id_rsa.pub”) into the Key subsection.
Install Git on macOS
The Git command line utility comes as part of the Xcode Command Line Tools package, which is included with the Xcode app. Because I plan to do iOS app development, I installed the latest Xcode app from the macOS App Store on my MacBook.
Before using Xcode (and Git), I have to accept the Xcode and Apple SDKs license by running Xcode after installation or using the command line like so:
sudo xcodebuild -license
# Type “agree” to accept the license
# Test out Git command line
git -—version
According to the web, if you want only the command-line developer tools without installing the Xcode app, you can run this command instead:
Clone the Repository
On the GitHub website, open the newly created repository and click on the green “<> Code” dropdown. Select SSH and copy the SSH URL, “git@github.com:myuser/myrepo.git”, which we will need below. (If you select the HTTPS URL, “https://github.com/myuser/myrepo.git”, you will be prompted to input the GitHub username and password.)
On your macOS or Linux terminal (in my case, Ubuntu under WSL on Windows 10), I ran the following:
ssh -T git@github.com
# Output from macOS slightly differs from Linux
The authenticity of host 'github.com (140.82.114.4)' can't be established.
ECDSA key fingerprint is SHA256:p2QAMXNIC1TJYWeIOttrVc98/R1BUFWu3/LiyKgUfQM.
This key is not known by any other names.
# Answer yes to add github.com to your known trusted hosts (stored in ~/.ssh/known_hosts)
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'github.com,140.82.114.4' (ECDSA) to the list of known hosts.
Hi myuser! You've successfully authenticated, but GitHub does not provide shell access.
# Set default identity for commit operations
git config --global user.email "myuser@mydomain.com"
git config --global user.name "First Last"
# Show existing git configuration settings
# Note: If you set a username and password, they would be exposed below
git config --list
# Clone the repository to your local client
git clone git@github.com:myuser/myrepo.git
Cloning into 'myrepo'...
Warning: Permanently added the ECDSA host key for IP address '140.82.113.3' to the list of known hosts.
remote: Enumerating objects: 4, done.
remote: Counting objects: 100% (4/4), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 4 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (4/4), done.
The last command above will clone the repository files to your local “./myrepo” directory.
Note: Strangely, the “~/.ssh/known_hosts” file could contain duplicate entries. Not sure why, but they do no harm.
Check In Your Project
Copy or move your project source files into the “./myrepo” directory. If you are migrating from another source control like Subversion, make sure to delete any specialized folder like “.svn” before copying or moving.
Check in your project files to GitHub:
cd myrepo
# Show the current Git status including unchecked-in files and directories
git status
On branch main
Your branch is up to date with 'origin/main'.
Untracked files:
(use "git add <file>..." to include in what will be committed)
xxxx.php
xxxx.php
xxxx.php
xxxx.php
templates/
views/
nothing added to commit but untracked files present (use "git add" to track)
# Add all untracked files and directories recursively
git add .
# Show the newly added files
git status
# If you have a file or directory erroneously added, you can remove it
git rm --cached file_name
git rm -r --cached directory_name
# Once you are certain there are no extraneous files that you do not wish to check in,
# Commit changes to your local repository
git commit -m "initial check-in comment"
# Check status
git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
(use "git push" to publish your local commits)
nothing to commit, working tree clean
# Upload local changes to the remote repository
git push origin main
# If everything is pushed to remote, you should see the following status
git status
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
The master branch which you created in GitHub is labeled “main” by default. The “origin” refers to the remote GitHub server (of which your local repository is a clone of), so “origin/main” refers to the master branch on the remote GitHub repository.
If you go to the GitHub website, you should now see your project files in the repository.
Some references: