Linking a Repository to GitHub

In Git, the command for working with remote repositories is git remote. A local repository can have multiple remote repositories. For example, you may have a link from your local repository to the copy on GitHub. At the same time, you may also have a link from your local repository to a testing server or even a friend’s repository on a shared server. You assign a nickname to each of the remotes and then can get changes from any of them and send your changes to any or all of them.

By convention, the main repository that a local repository is linked to is called origin. But you can call a remote by any nickname you want. To add a remote, you need the URL for the repository. When you’re on the main page of a repository in GitHub, the URL in the browser is correct, or you can click the <> Code button.

Downloading a Remote to Your Computer

The command to create a new repository on your local computer linked to a remote is git clone. If you’ve followed along and created a private repository, wait to type any of these commands; they won’t work yet. If you’ve followed along and created a public repository, use this command:

git clone <url_of_the_repository>

Git creates a new directory and copies the remote repository with all its branches and history. The working directory of this new repository will be clean. If you don’t want a local directory named the same as the remote, tell Git to use a different name for the local.

git clone <url_of_the_repository> <local_name>

Now, you have an exact copy of the remote on your local computer, and the two are linked. If you added a readme, .gitignore, or license, or are cloning a repository that already contains items, you can start branching, making changes, and merging. If you have an empty remote repository, Git warns you it’s empty. Remember from earlier lessons that you must have at least one commit to main before you can start branching and working.

Extra Steps for Private Repositories

When working with private repositories, you must authenticate when you git clone. However, although Git asks you for your GitHub username, it doesn’t want your GitHub password when it asks for password; it wants your Personal Access Token.

Before you learn about Personal Access Tokens, you can access a remote without generating a token if you use the GitHub Desktop app or authenticate using SSH. In the screenshot above, notice the “SSH” tab for the Code window. Clicking that starts the SSH process. You’ll see how to clone using the GitHub Desktop app during the next video demo.

Personal Access Tokens

As you might have seen, you can do much more than look at a repository while on the GitHub website. You can also:

• Make comments
• Interact with other repositories
• Host websites
• And more

You access all these features using your GitHub username and password. When linking a remote repository to a local repository, the local repository needs only a few permissions. Using your username and password creates a security hole because it can access many things that have nothing to do with the repository. Instead, the solution to this at GitHub and other places has been the Personal Access Token (PAT).

When you create a PAT, you give it specific permissions to specific repositories or other parts of GitHub. Aside from using the PAT to link a repository, you can use it with any other client app that needs access to your repositories. The token expires after a set number of days. Although you should secure the token just like any other password, you can quickly revoke it without resetting your entire GitHub account password if it’s leaked. That’s much safer.

On the GitHub website, you can create a new PAT from the Settings option in your Profile menu in the top right corner of the page.

At the bottom of the Profile Page’s left pane is “<> Developer Settings”. That contains the link for “Personal access tokens”. There are two kinds of tokens: classic and fine-grained. They work the same way. Unless you need to create a classic token because your IDE or another app that wants to use GitHub on your account requires it, create fine-grained ones.

You get a form to create the token once you click the “Generate new token” link. You assign it a name and what the token is for. For example, you might want one token to use when working but put a different token into your automated build scripts. You also have to assign an expiration date. All PATs have an expiration date as part of the security. When the token is about to expire, GitHub starts sending you emails reminding you to renew it or make a new one.

Then, you need to assign which repositories this token can access and what kind of access it has. After choosing which repositories, you decide on permissions. This is a long list and is certainly “fine-grained”. For a basic link of a local repository to a remote repository, all you need to grant is read and write permission for “Contents”. This is in the “Repository permissions” section.

After you click the button to generate the token, GitHub shows you the token. This is the only time you can see this token on GitHub, so copy it to the clipboard. Then, it’s a good idea to immediately attempt a Git command that requires authentication so you can paste the PAT where Git asks you for the password.

Conflicts with an Existing Repository

If you already have a Git repository on your computer and want to link it to a GitHub remote, it’s important that you leave the options for README, .gitignore and LICENSE blank so the remote is completely empty.

You’ll have conflicts if you have files and commits in your local repository and files and commits in your new remote repository. This is another version of the merge-conflicts problem you saw in the previous section. Also, the two repositories don’t have a common history, so when Git looks at the commit hashes in the logs, it can’t find a match, so it doesn’t know how to make the merge.

You might wonder if it ever happens that GitHub and your version of Git have generated the same UUID by chance. For modern-form UUIDs, you have a 50 percent chance of getting a duplicate in a pool of 2.71 quintillion. A quintillion is a 1 followed by 18 zeros. Even that is only a 50 percent chance of a duplicate. So, it’s highly unlikely that your local and GitHub will have accidentally generated a duplicate commit ID.

When linking locals and remotes, it’s best if one of the destinations is empty. If you’re curious, you can force Git to link them using git pull --rebase or git push --force, but those commands can cause problems and aren’t recommended. But at least now you know what terms to research if you’re curious.

Sending Your Repository to the Remote

In the local Git repository, you add the remote by typing this command:

git remote add origin <the_url_of_the_repository>

Confirm success by executing the git remote command without any other inputs to get a list of the nicknames of this repository’s remotes. To see the actual URLs that go with the nicknames, add the -v option.

git remote -v

In the list, origin is listed twice. Not only can you have multiple remotes for a repository, but you can also have a different remote for getting changes and for publishing changes.

After setting the remote, the next step is to switch to main using git switch main. Then, you can send your repository to the remote with push.

git push -u origin main

You only need to use -u origin for a branch’s first push. The -u option sets which remote is the default for this branch. You can have different branches point to different remotes. That way, in the future, you don’t have to specify which remote for each command when you want to send to or copy from your default. When you have multiple remotes, you need to specify the nickname when you want to tell Git not to use the default. Just don’t use the -u because that sets the default.

This only pushes the main branch. If you want to push other branches, you add each branch name separated by a space:

git push origin <this_branch> <that_branch>

You can also just push all the branches:

git push --all

For either public or private repositories, you need to enter your username and PAT to push. Now, if you check on GitHub, you see all the files from your repository and all the branches you pushed in the branches dropdown.

Copying Changes to Your Local

Now that you’ve gotten the local and the remote linked and can push your changes, you can learn how to bring changes to your local. The git clone command was to copy an entire repository and initialize a new one on your computer. For an existing, linked repository, get the new changes from the remote using:

git pull

This is like git merge when everything is local. If your working directory has no pending changes, the updates download to your local. If your working directory has pending changes that would be modified, Git requires you to git stash or git commit before it pulls in the changes. If you’ve made changes that would cause a conflict with a local merge, you get conflicts with a pull. The process for resolving the conflicts is the same as when everything is local.

When the remote has a branch you don’t have locally, you can’t always git switch to the branch because your copy of the repository might not know it exists.

You can see all the branches your local repository knows about using git switch -a. You can switch to any of these branches. For remote ones, you can specify the branch name; you don’t have to type the whole path.

When a branch has been created on the remote that doesn’t show up in git branch -a, you must let your copy of Git update its list of known branches. The command for that is:

git fetch

The fetch command tells your copy of Git that the branch exists and pulls the changes into the repository. They won’t appear in your working directory until you switch to the branch.

When you are the only developer contributing to the repository, these are all the commands you need. After the demo, the lesson will wrap up by showing you how to use fork and pull requests, the two features mentioned at the beginning of this lesson that are specifically for multiple contributors.