- A Git Tutorial, Slightly Focusing on CE-Toolchain Projects
- 05 Jan 2020 07:22:15 pm
- Last edited by commandblockguy on 28 Jun 2021 06:51:31 pm; edited 7 times in total
So, recently I've noticed that several people have been trying to add their code to GitHub so that others could look at it. I know that when I first started using Git and GitHub, they were quite confusing to me, so I've decided to write a guide to hosting calculator projects on GitHub. I'll cover what Git and GitHub are intended for, the basic concepts behind them, and how to use them for your project.
TL;DR for a basic setup:
Don't use GitHub's file upload interface.
Download the Git command line interface.
Create a new repository on GitHub, with the "Initialize this repository with a README" box unchecked.
Open the command line in the folder that contains your makefile and src folder (shift right-click on Windows).
Create a file called .gitignore (no extension) with the following contents:
Code:
Run the following commands:
Code:
Once you've updated a file and want to sync the changes to the repository, run the following:
Code:
(end TL;DR)
What is Git?
Git is a version control system. It was designed to be used to keep track of the history of a code project and allow multiple people to work on the same project at the same time.
What is Git not?
A file hosting tool - Git only properly keeps track of text-based files, and you should not include binaries (8XPs, EXEs, etc.), which are the output of a compiler or an assembler, or ZIP files, which really don't play nice with Git. It's fine to include images and other manually-generated non-text files in a repo, but Git doesn't track them in the same way as with text files.
You can download Git here https://git-scm.com/downloads
What is GitHub?
GitHub is an online service that hosts Git repositories so that multiple people can easily access them.
What is GitHub not?
Git - You can use Git without GitHub, and you should probably familiarize yourself with Git before using GitHub.
A file hosting service - Most of the benefits of GitHub over another site (say, Mediafire, or Google Drive) come from Git. If your GitHub repositories are not proper Git repositories, you might as well be using another service.
How does Git work?
Git keeps track of changes to files using commits. Each commit contains information about what files were changed since the last commit, who made the changes, when the changes were made, and a message to help you remember what changed with that commit. You can easily restore a previous commit, or just see what the code looked like at that point.
All projects that use Git contain data called a repository, which is stored in a folder called .git. The folder that contains the .git folder is called the working directory because you work in it. For CE toolchain projects, this should almost always be the folder with the makefile in it. The .git folder is hidden by default. To use any other Git commands, you must first create a repository.
Creating a repository
You can create a repository in a folder (for CE toolchain projects, use the one that you run make in) by running "git init".
You can also make a copy of a repository that is already on GitHub using "git clone (URL)". This command downloads the repository and its associated files into a new folder. For example,
Code:
(shameless plug, I know.) would create the folder dino-run-ce, and download the source for Dino Run CE into it. You can then cd dino-run-ce, and run make without any further setup. This makes Git significantly more convenient than a zip with the source, for example.
The .gitignore file
You generally want Git to ignore automatically generated/binary files (8XPs, EXEs, the output of convimg, etc.). You don't have to store these files as you can regenerate them from the source, and the files are likely to change with every commit. This makes the repository much larger and commits harder to read through, and requires you to manually add them to each commit or have outdated binaries in your repository.
Luckily, Git includes an easy way to do this - .gitignore files. To use them, just create a file called ".gitignore" and add a list of folders you want to ignore. I recommend the following .gitignore file, as it should match all non-source files:
Code:
Now, from Git's perspective, these files basically no longer exist - you won't be asked to add them to commits.
Making commits
Now that we are ignoring the right files, how do we add the ones we actually care about to the repository?
Before making a commit, you have to add the files that you want to include in the commit. To get a list of the files that you can add, run:
Code:
The files that you have already added are in green, and the files that have changed but that will not be included in the next commit are in red.
To add the files to the next commit, run:
Code:
Once you are done adding files, you can create the commit by running:
Code:
Adding your repository to GitHub
Right now, the repository exists on your computer and can be used with all Git commands, but it is not backed up to GitHub so that others can access it.
To do that, you must first create a new repository on GitHub, but leave the "Initialize this repository with a README" box unchecked. This will make a blank repository on GitHub that we can write our local changes to.
Next, you will want to set up the repository on your machine to write to the one on GitHub (the "remote" repo) using "git remote add". The syntax is "git remote add (name) (URL)". By convention, the name for this type of setup is "origin". So, for example,
Code:
Finally, you must synchronize the changes in your local repository with the remote repo by pushing. Before pushing, it is good practice to run
Code:
to prevent conflicts. Then, you can run
Code:
The remote repository will only be updated with your code and commits when you push. You do not have to push after every commit - Git is running on your computer, and you can still use all of its features without pushing your code to GitHub. You only need to push when you want to share the code on your computer with others.
You should avoid using the GitHub web interface as much as possible. Although it may initially seem more convenient, it makes it much easier to accidentally use Git in a way that it wasn't intended for and make it much more difficult for other people to try your code. This only applies to your actual code - the web interface is the only way to create a repository, view the issues, create a wiki, and add releases. Any action besides these should be done in the Git command line. If you are unsure how to do something, feel free to ask here or in IRC - I'll be sure to help out and update the guide.
Adding releases to GitHub
Since it's poor practice to include binaries in a Git repository, GitHub has another way of hosting them - the Releases tab.
To access the Releases tab, open your repository on the GitHub website and click on the Releases button above the file list. From there, you create a release by clicking "Draft a new release". Give it a tag like "v1.0" and a name and a description. Then, you can add 8XPs or a ZIP file to the file upload area by clicking and dragging or by clicking the upload area and selecting a file.
Coming Soon - Forks, Pull Requests, and Graphical Clients!
If anyone notices any inaccuracies or has scathing criticism or suggestions on how to improve this guide, please let me know - just keep in mind that this is intended as a beginner tutorial. Especially let me know if anything seems confusing - I'll do my best to clarify. If you have any (Git- or GitHub-related) questions, I'll either answer them here or attempt to find resources that would answer better than I could.
TL;DR for a basic setup:
Don't use GitHub's file upload interface.
Download the Git command line interface.
Create a new repository on GitHub, with the "Initialize this repository with a README" box unchecked.
Open the command line in the folder that contains your makefile and src folder (shift right-click on Windows).
Create a file called .gitignore (no extension) with the following contents:
Code:
bin/
obj/
src/gfx/*.c
src/gfx/*.h
Run the following commands:
Code:
git init
git remote add origin (the url of the repository plus ".git" - e.g. https://github.com/commandblockguy/test.git)
git add (a list of all files you need to build your project - probably something like makefile iconc.png readme.md src/*.c src/*.h src/gfx/*.png src/gfx/convimg.yaml)
git commit -m "Initial commit"
git push -u origin master
Once you've updated a file and want to sync the changes to the repository, run the following:
Code:
git add (file that changed)
git commit -m "Your commit message here - whatever text you want."
git push
(end TL;DR)
What is Git?
Git is a version control system. It was designed to be used to keep track of the history of a code project and allow multiple people to work on the same project at the same time.
What is Git not?
A file hosting tool - Git only properly keeps track of text-based files, and you should not include binaries (8XPs, EXEs, etc.), which are the output of a compiler or an assembler, or ZIP files, which really don't play nice with Git. It's fine to include images and other manually-generated non-text files in a repo, but Git doesn't track them in the same way as with text files.
You can download Git here https://git-scm.com/downloads
What is GitHub?
GitHub is an online service that hosts Git repositories so that multiple people can easily access them.
What is GitHub not?
Git - You can use Git without GitHub, and you should probably familiarize yourself with Git before using GitHub.
A file hosting service - Most of the benefits of GitHub over another site (say, Mediafire, or Google Drive) come from Git. If your GitHub repositories are not proper Git repositories, you might as well be using another service.
How does Git work?
Git keeps track of changes to files using commits. Each commit contains information about what files were changed since the last commit, who made the changes, when the changes were made, and a message to help you remember what changed with that commit. You can easily restore a previous commit, or just see what the code looked like at that point.
All projects that use Git contain data called a repository, which is stored in a folder called .git. The folder that contains the .git folder is called the working directory because you work in it. For CE toolchain projects, this should almost always be the folder with the makefile in it. The .git folder is hidden by default. To use any other Git commands, you must first create a repository.
Creating a repository
You can create a repository in a folder (for CE toolchain projects, use the one that you run make in) by running "git init".
You can also make a copy of a repository that is already on GitHub using "git clone (URL)". This command downloads the repository and its associated files into a new folder. For example,
Code:
git clone https://github.com/commandblockguy/dino-run-ce.git
The .gitignore file
You generally want Git to ignore automatically generated/binary files (8XPs, EXEs, the output of convimg, etc.). You don't have to store these files as you can regenerate them from the source, and the files are likely to change with every commit. This makes the repository much larger and commits harder to read through, and requires you to manually add them to each commit or have outdated binaries in your repository.
Luckily, Git includes an easy way to do this - .gitignore files. To use them, just create a file called ".gitignore" and add a list of folders you want to ignore. I recommend the following .gitignore file, as it should match all non-source files:
Code:
bin/
obj/
src/gfx/*.c
src/gfx/*.h
Now, from Git's perspective, these files basically no longer exist - you won't be asked to add them to commits.
Making commits
Now that we are ignoring the right files, how do we add the ones we actually care about to the repository?
Before making a commit, you have to add the files that you want to include in the commit. To get a list of the files that you can add, run:
Code:
git status
To add the files to the next commit, run:
Code:
git add (file1) (file2) (file3)...
Once you are done adding files, you can create the commit by running:
Code:
git commit -m "Some message for the commit"
Adding your repository to GitHub
Right now, the repository exists on your computer and can be used with all Git commands, but it is not backed up to GitHub so that others can access it.
To do that, you must first create a new repository on GitHub, but leave the "Initialize this repository with a README" box unchecked. This will make a blank repository on GitHub that we can write our local changes to.
Next, you will want to set up the repository on your machine to write to the one on GitHub (the "remote" repo) using "git remote add". The syntax is "git remote add (name) (URL)". By convention, the name for this type of setup is "origin". So, for example,
Code:
git remote add origin https://github.com/commandblockguy/test.git
Finally, you must synchronize the changes in your local repository with the remote repo by pushing. Before pushing, it is good practice to run
Code:
git pull --rebase origin master
Code:
git push origin master
The remote repository will only be updated with your code and commits when you push. You do not have to push after every commit - Git is running on your computer, and you can still use all of its features without pushing your code to GitHub. You only need to push when you want to share the code on your computer with others.
You should avoid using the GitHub web interface as much as possible. Although it may initially seem more convenient, it makes it much easier to accidentally use Git in a way that it wasn't intended for and make it much more difficult for other people to try your code. This only applies to your actual code - the web interface is the only way to create a repository, view the issues, create a wiki, and add releases. Any action besides these should be done in the Git command line. If you are unsure how to do something, feel free to ask here or in IRC - I'll be sure to help out and update the guide.
Adding releases to GitHub
Since it's poor practice to include binaries in a Git repository, GitHub has another way of hosting them - the Releases tab.
To access the Releases tab, open your repository on the GitHub website and click on the Releases button above the file list. From there, you create a release by clicking "Draft a new release". Give it a tag like "v1.0" and a name and a description. Then, you can add 8XPs or a ZIP file to the file upload area by clicking and dragging or by clicking the upload area and selecting a file.
Coming Soon - Forks, Pull Requests, and Graphical Clients!
If anyone notices any inaccuracies or has scathing criticism or suggestions on how to improve this guide, please let me know - just keep in mind that this is intended as a beginner tutorial. Especially let me know if anything seems confusing - I'll do my best to clarify. If you have any (Git- or GitHub-related) questions, I'll either answer them here or attempt to find resources that would answer better than I could.