23  GitHub Repositories

A repository (often shortened to “repo”) on GitHub is like a storage space where all the files and their revision history for your project are kept. Repositories are used to organize your work and collaborate with others, track changes to your code, and manage various versions of your project.

23.1 Create

Using GitHub repositories, you can initialize your project with essential files such as a README, .gitignore, and a license to provide structure and clarity. Here’s a detailed guide on how to do this, including explanations of what each of these components is.

  1. Sign In to GitHub
    • Open GitHub in your web browser.
    • Sign in to your GitHub account. If you don’t have an account, you need to create one (see GitHub Setup).
  2. Navigate to Your Dashboard
    • Once signed in, you’ll be taken to your GitHub dashboard. Here, you can see your existing repositories, recent activity, and more.
  3. Start a New Repository
    • Click the + icon at the top right corner of the page, and select New repository from the dropdown menu.
  4. Fill in Repository Details
    • Repository Name: Choose the name hello-github for your repository. Names should always be concise yet descriptive.
    • Description: (Optional) Add a short description of your project. This helps others understand the purpose of your project.
    • Public or Private: Choose whether your repository will be public (visible to everyone) or private (visible only to you and people you explicitly share it with). Select public.
  5. Initialize the Repository
    • README: A README file is a markdown file (README.md) that serves as the front page of your project. It’s a place to introduce and explain your project. Check the box to Initialize this repository with a README to create this file automatically.
    • .gitignore: A .gitignore file specifies which files and directories should be ignored by Git. This is useful to exclude files that are not necessary to be tracked, such as temporary files and files with secret API information. You can select a template that matches your project’s language or environment (choose Python).
    • License: A license file specifies the terms under which your project can be used, modified, and shared by others. Choosing a license ensures that others can legally use and contribute to your project. GitHub provides a variety of licenses to choose from, such as MIT, Apache, GPL, etc. We use the MIT License, which allows anyone to do anything with your code as long as they include the original copyright and license notice.
  6. Create Repository
    • Click the Create repository button to create your new repository on GitHub.

23.2 Clone

Cloning a repository means creating a local copy of a remote repository on your computer. This allows you to work on the project files offline, make changes, and then sync those changes back to the remote repository on GitHub.

  1. Open GitHub and Find Your Repository
    • Open GitHub in your web browser and navigate to your hello-github repository.
    • On the main page of the hello-github repository, click the green Code button.
  2. Select Cloning Option
    • In the dropdown menu, click on Open with GitHub Desktop. This will prompt GitHub Desktop to open and start the cloning process.
    • If prompted by your browser to open GitHub Desktop, confirm the action.
  3. GitHub Desktop Opens and Cloning Begins
    • GitHub Desktop will open and display a dialog box to confirm the local path for the repository.
    • Choose the toolkit-lab directory on your local machine where you want to clone the hello-github repository. This will create a folder named hello-github inside the toolkit-lab directory.
    • Important: Always ensure that the directory is not synchronized with any cloud storage services such as iCloud, OneDrive, or Google Drive. Syncing with these services can cause conflicts and issues with your Git repository.
  4. Clone
    • Click Clone to download the hello-github repository to your local machine.
  5. Open the Repository in GitHub Desktop
    • Once cloning is complete, GitHub Desktop will automatically open the hello-github repository.

23.3 Commit

After cloning your hello-github repository to your local machine, the next step is to start working on your project files. We’ll use Visual Studio Code (VS Code) to open the repository and make changes.

Opening the hello-github Repository in VS Code

  1. Open VS Code
    • Launch Visual Studio Code on your computer.
  2. Open the Cloned Repository
    • In VS Code, click on File > Open Folder….
    • Navigate to the toolkit-lab/hello-github directory where you cloned your repository and select the hello-github folder.
    • Click Select Folder to open the repository in VS Code.
  3. Create or Modify Files
    • You can now create new files or modify existing ones directly in VS Code. For example, to create a new Python file:
      • Right-click in the Explorer panel (left sidebar) and select New File.
      • Name the file script.py and add some Python code to it. Save your changes.
  4. View Changes in GitHub Desktop
    • After making changes in VS Code, switch back to GitHub Desktop. You will see the changes listed in the left sidebar.
  5. Pull Changes
    • First, make sure that there are no changes in the remote hello-github repository that you don’t have locally. You can pull them by clicking the Fetch origin button and then Pull to update your local repository with the latest changes.
  6. Stage Changes
    • Staging means selecting which changes you want to include in your next snapshot (commit) of the repository.
    • In GitHub Desktop, you will see a list of changed files. To stage changes:
      • Check the boxes next to the files you want to include in your commit.
      • If you want to stage all changes at once, you can click the Stage All button.
  7. Commit Changes
    • Committing means saving your staged changes with a descriptive message that explains what you’ve done. This message helps you and others understand what changes were made and why.
    • Write a brief but descriptive commit message in the Summary field. For example, “Add initial Python script”.
    • Click Commit to main to save the changes to your local repository.
  8. Push Changes
    • After committing changes, click the Push origin button at the top to upload your changes to the remote hello-github repository on GitHub.

23.4 Tips

  • Commit Often: Make small, frequent commits with clear messages. This makes it easier to track changes and revert if necessary.

  • README: A well-documented README file is crucial. It should provide an overview of the project, how to install and use it, and any other relevant information.