Intro to Git, Github and VSCode

Hi, this is Louis Liu. In this tutorial, I will guide you through some basic operations in Git, GitHub, and VSCode. (The Mandarin Translation is on the second page.)

If you haven’t yet completed the LICENSE signing for the Echo-Land game project under the CruxAbyss game development team, please make sure to do so first. Before signing, you’ll need to familiarize yourself with some fundamental GitHub operations, such as:

1. What are Git and GitHub
2. What is a Repository (Repo) in GitHub
3. What is an Issue in a GitHub Repo
4. What is a Pull Request (PR) in a GitHub Repo
5. How to modify, add, or delete files in a GitHub Repo

Once you have a good understanding of these operations, you’ll be ready to complete the signing process on your own.

What Are Git and GitHub

Git is a distributed version control system for code.

Let’s start by understanding what a “version control system for code” means.

Essentially, Git acts as a historical recorder for your code. Why do we need this? In real-world development projects (coding), it’s almost impossible to write all the code at once and have the entire project running smoothly. Typically, we modularize the code, breaking down a large task (large codebase) into smaller tasks (smaller pieces of code) that are handled separately, and then gradually integrating these smaller pieces into the larger codebase.

At this point, Git becomes incredibly important as a historical recorder for your code because it helps you document your progress at various stages. For example, if your manager asks you to build a robot that can automatically send and receive emails, your first step should be to break down this large task: “a robot that can automatically send and receive emails” into two smaller tasks: “a robot that can automatically receive emails” and “a robot that can automatically send emails.” Let’s say you work on the “receive emails” part first. Once completed, wouldn’t it be wise to save your progress? This is where Git comes in handy — you can use Git to record the current state of your code and then move on to the next task, “a robot that can automatically send emails.”

You might wonder: Why do I need to record this? Can’t I just complete the two tasks separately without using Git?

Yes, you could, but can you guarantee that while working on the second task, you won’t accidentally modify the code for the first task? For instance, while writing code for the “send emails” functionality, you might suddenly realize that you could optimize the code for the “receive emails” part, so you make some changes. But then you find out that your optimization was entirely wrong, or you accidentally deleted some of your previous code, causing the program to stop running. Now, you want to revert to the state when you just finished writing the “receive emails” functionality to compare and figure out what went wrong. You start using Undo (Ctrl + Z or Command + Z), but find that you can’t get back to that exact state. Now, you’re left staring at your broken code, forced to painstakingly fix it.

But what if you had used Git? It would be incredibly convenient, you could simply use Git to revert to the last recorded state of your code and compare the differences between the last version and your current one. That’s why Git is essential in almost all large-scale project developments.

Now, why is Git called “distributed”?

Because Git allows multiple developers to collaborate on the same project. For example, you can share your project along with its Git repository with others, and everyone can work on it simultaneously, optimizing code, proposing new features, and more. Git allows for code comparison, branch creation, code merging, and so on.

GitHub is a platform that integrates Git for hosting code repositories.

This platform provides a way for developers worldwide to collaborate on various projects, with added functionalities and features.

That’s why we host our game project files on GitHub: firstly, it has Git to help us record the historical state of all files in the project. Additionally, GitHub’s built-in features like webhooks and code review tools can significantly enhance our game development process.

What Is a Repository (Repo) in GitHub

In GitHub, a Repository (often abbreviated as Repo) is essentially a “code repository.” This is where all the files and their history related to a project are stored. For instance, the game project we’ve uploaded to GitHub is currently one of the Repositories in our GitHub account, as shown in the image below:

Repositories are central to how GitHub works. They act as the home for your project’s files, including source code, documentation, and any other assets related to the project. Within a Repo, you can track changes to your files over time, collaborate with others, and manage different versions of your project.

What Is an Issue in a GitHub Repo

Imagine this scenario:

You’re browsing GitHub, looking for some interesting code projects to try out. Suddenly, you stumble upon a repository (Repo) that contains a Canvas bot that automatically completes your homework. You’re instantly intrigued! You download the Repo to your local machine and follow the instructions in the repository’s README file to learn how to use the bot to do your Canvas assignments.

(Quick note: What is a README file? It’s essentially a “User Guide” that most repositories include. The reason it’s called “READ ME” is that the code author wants to ensure others understand what the Repo does. So the README contains an introduction to the Repo and details on how to use it.)

However, as you run the code from the Repo, you encounter an error! You’re confident that you’ve followed every step outlined in the README file. This likely means one of two things: either the author’s code has a problem, or there’s an issue with the README instructions. Either way, the issue lies within the files of the Repo — something is wrong or there’s a bug. Since you’ve discovered this problem and would like the author to fix it (Come on!! This bot could help you with your homework!!), you can go to the GitHub repository’s Issues section to report this problem and provide feedback on the bug. If you have a bit more technical skill, you could even debug the code, identify the exact source of the error or bug, and then report it via an Issue.

Here’s an example of where you would submit/report an Issue on GitHub:

It’s important to note that in the Issues section of a GitHub repo, you’re not just limited to reporting bugs. You can also suggest improvements to the code or request the addition of new features. For example, you might be very satisfied with the Canvas bot that automatically does your homework, but you also wish it could help you complete online Canvas exams. Since this feature isn’t currently available in the repository, and you might not have the coding skills to add it yourself, you can submit a feature request in the Repo’s Issues section. This way, you can inform the code author of your desire for this functionality, and they may consider adding it in the future.

Overall, here are the procedures to open an issue of a Repo on Github

1. Navigate to the Repo: Go to the GitHub repository where you encountered the issue or want to suggest an improvement.
2. Access the Issues Tab: Click on the “Issues” tab, typically located near the top of the repository page.
3. Create a New Issue: Click the “New Issue” button to start reporting your problem or suggesting a new feature.
4. Describe the Issue or Request: Give your issue a clear title and provide a detailed description. If you’re reporting a bug, include information about what you were doing when you encountered the error, any relevant error messages, and steps to reproduce the issue. If you’re suggesting a feature, explain why the feature would be useful and how it could be implemented.
5. Submit the Issue: Once you’ve filled out the details, click “Submit new issue” to send it to the repository’s maintainers.

What is a Pull Request (PR) in a GitHub Repo?

Imagine this scenario:

You’ve created a bot that automatically completes assignments on Canvas, and you’re really pleased with it. However, you also wish that this bot could help you complete Canvas online exams, but the current repository (repo) doesn’t include this feature yet. However, being a skilled developer, you’re confident that you can add this new functionality to the repo. So, you spend a few days improving the repo you downloaded locally, and you successfully implement the feature that enables the bot to take online exams on Canvas! Feeling generous, you realize that such a tool shouldn’t be kept to yourself — it should benefit all students!

You decide to upload your improved repo to GitHub. But there’s a catch: you can’t directly modify the original author’s repo on GitHub because you don’t have the necessary permissions. Also, creating a new repo and uploading it wouldn’t be appropriate because your code is based on the original author’s work, where they created the bot that completes assignments on Canvas. Therefore, following international conventions and basic ethical guidelines, you should submit a Pull Request (PR) to the original author’s repo on GitHub. If the original author accepts your PR, your code will be merged into the repo, and your name will be added to the list of contributors for that project.

But this raises the question: What exactly is a Pull Request (PR)?

A PR is essentially a request to the original author, asking them to consider integrating your changes into the current repository. It’s as if you’ve written a new poem in the style of the “Tang Poems” and submitted it to the “300 Tang Poems” collection. If the curator of the “300 Tang Poems” accepts your submission, the collection would become “301 Tang Poems,” and you would be recognized as one of the contributors.

OK, so how do you submit a PR? Can you just click the Pull Request button on the repo on Github?

Actually, it’s not that simple. Please read the next section!

How to Modify, Add, or Delete Files in a GitHub Repository

Now, let’s simulate a scenario where you’ve made changes to files in a GitHub repository and want to submit a Pull Request (PR) for those changes.

First, let’s clarify one point: if you’ve downloaded the repository to your local machine and made changes there, you won’t be able to submit a PR directly. Why? Because GitHub requires that the repository you’re modifying must be connected to the same Git repository to submit a PR.

You might wonder, “Oh, so should I just create a new Git repository for my local changes?”

Absolutely not! If you create a new Git repository for your local changes, it will be a completely new Git instance, different from the original author’s repository. The history recorded by your Git (version control system) will only include the changes you’ve made, not those made by the original author. This is because your Git only starts recording from the state of the code you initially downloaded (like starting a test from 60% completion without knowing what happened from 0% to 60%). On the other hand, the original author’s Git tracks all their changes, but none of yours (like a test recording only the progress from 0% to 60%).

A shared Git repository should record the entire process from 0% to 100%, without missing any steps!

So, how do you merge the changes you’ve made (from 60% to 100%) with the original author’s changes (from 0% to 60%)?

Answer: You need to start by copying the original repository, including its Git history, to your local machine, and then make your modifications. You should not create a new Git repository!

But why is it necessary to use the same Git repository to make improvements to a repo? What if I don’t want to use the same Git repository?

Answer: You can indeed choose not to use the same Git repository, but:

1. If you intend to make your improved repository public but use a different Git repository, it effectively erases the contributions (from 0% to 60%) of the original author, which is generally considered unethical.
2. From a collaboration standpoint, this approach can lead to a lack of consistency, leaving other developers unsure which repository to contribute to. For instance, you might improve the code’s readability, while someone else adds a new feature. If you’re not using the same Git repository, the project could split into two separate repositories, preventing the integration of these different improvements and reducing overall development efficiency.

Remember we mentioned earlier that Git is “distributed”? Git allows multiple developers to collaborate on the same project, but the key is that you must use the same “version control system” or “historical recorder for code” to ensure that everyone is working on the same repository.

Example: Imagine A and B both borrowed C’s homework to copy, but since C is known as the class underachiever, his homework typically scores only 60%. A and B must be very careful while copying to avoid making the same basic mistakes. After making their own corrections, they both finish the homework. However, since A and B are very generous, they decide to share their corrected versions with the whole class. The problem is, whose version should be shared — A’s or B’s? If one is shared and later D, the top student, wants to improve it further, what happens to the other version? To avoid this issue, A and B decide to compare their work and combine their efforts into one perfect version (similar to merging two repos through a PR).

This example reflects the principle that when collaborating on a repository, everyone must use the same Git. If A and B both share their versions, it’s like splitting one modified repository into two, as they didn’t use the same Git. This forces the rest of the class to choose between the two, which is inefficient. By combining their efforts, they ensure that others can benefit from a single, improved version — just as using the same Git allows for a unified repository.

Now that we’ve established the importance of using the same Git when collaborating on a repository, let’s dive into the practical steps.

Since you need to copy the original repository along with its Git history to your local machine from the start, how do you do this? A normal download won’t include the Git history. Therefore, you need to click “Fork” next to the repository. This will copy both the original repository and its Git history to your GitHub account.

Let’s go through this step together. Follow along with this tutorial using a sample repository designed for learning GitHub, no need to worry about causing any issues.

First, click “Fork” on the repository page. See the image below for reference:

After clicking, you’ll see a new page. Don’t change anything, simply click the green “Create fork” button in the lower right corner:

Once you’ve clicked, wait a few seconds, and you should see the following page:

In the image, the information highlighted in the red box indicates that this is the repository you’ve forked (in this case, Deep0Thinking forked the Repo). You can compare it with the original author’s repository to see the differences (in this case, this forked Repo is up to date, so currently no changes between the forked Repo and the original Repo).

Now that you’ve forked the repository, the next step is to clone it to your local machine. This will allow you to make changes, add new features, or delete files, all while maintaining a connection to the original Git history.

To clone your forked repository:

1. Make sure you have “git” installed on your computer, if you don’t have git installed, please check here: https://git-scm.com/downloads

2. Go to your forked repository on GitHub and click on the “Code” button. You’ll see an option to clone using HTTPS, SSH, or GitHub CLI. Copy the URL provided (by clicking on that icon next to the URL inside the red box):

3. Open your terminal (on MacOS, you can press command + spacebar, then type in terminal and press return to open your terminal).

4. In terminal, type the following command:

git clone <your-copied-URL>

This command will create a local copy of the repository on your computer.

5. Navigate into the cloned repository directory:

cd <repository-name>

Now that your repository is cloned locally, you can start by navigating to the cloned repository directory (your project folder). Once you’ve opened this folder in your preferred text editor (in this case I’ll be sticked with VSCode to demonstrate), go ahead and write something in it, anything you like, just to create a change.

Next, you’ll need to save the file locally (on MacOS, you can press command + s to save a file locally), which will register the change you’ve made. Once the change is saved locally, you’ll see a red icon or indicator in VSCode, signaling that there are uncommitted changes for Git in your working directory.

(Here, I did some changes to the `ok.md` file)

Now, let’s prepare to commit your changes. In the Source Control panel, click on the red-highlighted icon (typically a “+” symbol) next to that ok.md file. This action stages the file, indicating that you want to include this change in your next commit.

If you’ve modified multiple files and only want to commit some of them, you can selectively stage individual files by clicking the “+” icon next to each file you wish to include. This selective staging is useful when you’ve made changes across different files but want to commit only the changes that are complete and ready for version control.

After staging your changes, the next step is to commit them. In the message box under “Source Control,” write a clear and concise commit message. This message should briefly describe what changes were made to the files you’ve staged. Note that writing a commit message is mandatory; without it, Git will not allow you to commit your changes.

It’s essential to develop the habit of writing meaningful commit messages. These messages act as a log for your code’s history, and vague or unclear messages can make it difficult to track the progress of your project or understand the purpose of past changes. Properly written commit messages make it easier to manage your project over time.

Once you’ve written your message, click the green “Commit & Push” button. This action records your changes in the Git history and pushes them to your remote repository (e.g., on GitHub).

The “Commit changes” action in Git is simply a way of recording your changes — it’s not the same as creating a Pull Request (PR). A PR is a formal request to merge changes from one repository (a forked one of the original repo) into another (the original repo).

Commit changes are typically minor and incremental, helping to keep a record of small updates or progress steps (think of it as taking snapshots of your work to prevent data loss). In contrast, a PR is more significant, akin to submitting a complete and finalized version of your work for review and integration into the main project.

You should use commit changes regularly to keep track of your progress. However, reserve PRs for when you have completed a substantial part of your work that meets specific project goals.

Now, let’s create a PR to see how it works. After you’ve made and committed several changes that fulfill a certain project objective, click on the icon highlighted in red (usually labeled “Pull Requests”) in GitHub or in your GitHub repo’s interface:

You’ll be directed to a new page where you can create a PR. Here, you should:

• Title: Provide a title that briefly summarizes the changes you are proposing to merge.
• Description: In the description field, add detailed information about the changes. Explain what was modified, why the changes were made, and any other relevant context.
• Labels: Don’t forget to click on the “Labels” section and select the appropriate label if possible (like “Bug Fixed”, “Typo Fixed”…). This categorizes your PR, making it easier for reviewers to understand the scope and purpose of your changes.

After filling out these fields, click the “Create pull request” button.

Once the PR is created, it will appear on the PR page of the repository, and the repository’s maintainers will be notified for review:

The maintainers will review the PR based on its contribution and relevance to the project. If the changes meet the necessary standards, the PR will be merged into the original repository.

Remember, a PR is essentially a request to merge the code from your forked repository into the original one. If the PR is accepted, both repositories will be synchronized, with the original repository incorporating your changes.

Additional Notes

• Commit Messages: Aim to be as descriptive as possible. Instead of writing “fixed bugs,” you might write “fixed null pointer exception in email processing module.” This level of detail will save you and your team time when reviewing past commits.
• Branching: Before working on a new feature, create a new branch. This keeps your work isolated until it’s ready to be merged.
• Merge Conflicts: When working on a team, you might encounter merge conflicts. These occur when changes from different branches conflict with each other. Git will require you to resolve these conflicts manually.

With these steps, you should now have a solid foundation for using Git, GitHub, and VSCode in your development workflow. Happy coding!!!!

Pages: 1 2