Picture this scenario: you're an artist, or a musician, or a writer working on a game project. You want to upload some assets to your project so that your team programmer can use them while developing a new feature. So you head over to your project's GitHub page to upload your files and...what the heck is going on?! This doesn't look anything like Dropbox. You need to download some special tool?? What the hell is a "pull request"? Why do I have to do so many steps to upload my file? Help!!
Well, I'm here to help walk you through it as best as I can. Git is a powerful and complex system for managing different versions of code, and it was initially intended for a highly technical audience. This can make it super intimidating and hard to understand, even for people with programming backgrounds. Despite that, getting the basics down is something that you can do. Yes, you. I promise you, you've got this.
Before we get started actually diving into git, let me reassure you: being confused does not make you dumb. It's totally reasonable to feel overwhelmed and confused by the onslaught of weird terminology. Sometimes I think that git documentation was written to be intentionally impossible to understand. But don't worry, because this is something that is 100% doable, despite how it may appear at first.
Feeling ready? Let's get started!
Chances are, your team's git project is hosted on GitHub. This is the standard git provider for 99% of people, especially smaller teams. Before you can make changes, you'll need to create a GitHub account, which you can do on their website. I also highly recommend downloading GitHub Desktop. If you choose not to do this, you'll need to rely on another git client, or a terminal, which is something you really probably don't want to do. For the rest of this article, I'm going to assume you have GitHub Desktop.
A git project is called a repository. It holds all the code and all the other files in your project. Basically, you can think of the repository as being the entire universe of all the files you care about. Much like Dropbox or Google Drive, the primary copy of the repository exists on a server somewhere (probably on github.com). This is called the remote repository. But where git immediately starts to differ from other file management services is that you need to download your own copy of the repository onto your computer.
The copy of the repository on your computer is called your local repository. Everyone on your team will have their own local repository. These files are stored directly on your computer, and they don't necessarily stay directly in sync with the files in the remote repository. This means that when you make changes to your local repository, they don't get reflected in the remote repository until you request for that to happen. It's important to keep this in mind, as this is one of the core principles of how git works.
To download your team's repository, navigate to your project's GitHub page in your web browser. Make sure you're logged in. Click on the green "Code" button in the upper right area of the page, and select "Open in GitHub Desktop". This will download a local repository from the GitHub server and set up a connection between your new local repository and the remote repository. This process is called _cloning_, but you probably won't need to worry about that. Once the repository has been opened in GitHub Desktop, you can click the "Open in File Explorer" button to see all the downloaded files.
Rather than just being a collection of files on a server, a git repository contains much more information. It contains an entire history of the files, starting from when the repository was created up until now. The history has a number of checkpoints in it called commits, which represent distinct and accessible points in the project's history. You can use git to restore the state of the repository to any of these commits. This is one of the main features that makes git so powerful and so popular. In GitHub Desktop, if you click on the history tab, you can see the list of commits on the left. When you click on a commit, it'll show you a bunch of snippets of files. These represent all the changes that were made as part of that commit. Each commit represents not just a point in the history of the repository, but also a set of changes from the previous commit.
Every change made to a repository must be part of a commit. So in order to make changes to your local repository and upload them to the remote, you'll have to create a commit. Let's go over how to do that now.
Now that your local repository is set up, you're able to start editing your files. Suppose you change some images. You'll notice that in GitHub Desktop, you'll see the names of the files you edited in the "Changes" column. However, this doesn't mean that your changes have been saved and committed to the repository. Currently your changes are considered "unstaged". This means that git knows you changed the files, but it isn't sure if you want to include those changes in a commit or not. Before you can commit the files, you have to stage them. To stage the files, click the check box next to the file's name so that it's checked.
Once you've made all the changes you want to make, you can prepare your commit. Make sure any changes you want to be saved permanently are staged using the check boxes next to their names (and remember, you can always undo them after you commit if you want to!). Now underneath, enter a description of your changes into the box labeled "Description". This is called a commit message, and it's a portion of your commit that's used to explain what the commit is for. Usually people try to keep this at 1-2 sentences, but still try to be descriptive about what changed. Once you've entered your message, you can click the "commit" button, and your commit is made! So are we done yet?
You've made the commit on your local repository, but the remote repository doesn't know about it yet. This is because the two repositories only synchronize with each other when asked to. To make the remote repository accept the changes you've made on your local, you need to "push" your changes. You can do this by opening the Repository menu at the top and selecting "push". This will send your changes to the remote repository and ask it to accept them.
Synchronization is a two-way street, however. Suppose your team makes some more changes and you want to get those changes on your local repository so you can see them. You need to tell your local to accept changes from the remote repository. This process is aptly called a pull, as it's the opposite of a push. You can pull from the remote repository by going to the Repository menu at the top and selecting "pull".
Congratulations! You've published a change on git! See, I told you you could do it!
Your team's programmer may have asked you to create something called a "pull request" or a "PR". Not only does this sound weird and intimidating, but it doesn't show up in a lot of git documentation, which is extra confusing. This is because pull requests are a concept specific to GitHub, so not all git servers use them.
A pull request is sort of an intermediate step in between pushing a commit and having the commit accepted into the remote repository. It gives other people a chance to review your changes and examine and test them before they get permanently added to the remote repository's history. To make this happen, there are a few extra steps, so let's go over how it works.
Have you ever wanted to experiment with a potentially big change to a file, but not wanted to mess it up? To do this, a lot of people will create a new version of the file and edit that one instead. Suppose I'm creating an asset called `cute_dog.png`, and I want to make a big change to it, but I'm still kind of happy with the existing one. I might create a copy called `cute_dog2.png` and work on that copy instead. This way I get to keep both copies.
Git has a concept called branching, which kind of works like this, but for the entire repository. When you create a branch of the repository, you basically get a new copy of every file to work on, while the old version is preserved. These branches each get their own history, which means you can have people working on different potential changes to the same files at the same time without overriding each other. In larger teams, using branches is a critical part of the git workflow. It's also necessary for creating pull requests.
To create a new branch in GitHub Desktop, click the Branch dropdown and select New Branch. Name the branch something related to the changes you're trying to make. For example, if I was trying to make a new version of `cute_dog.png`, I might call my branch `new-cute-dog`. This is helpful for organization.
Now that you're on your new branch, follow the previous instructions all the way through. Once you've pushed your changes to the remote repository, you've got one more thing to do before your pull request is ready to go.
Now we need to create the pull request on the GitHub website. Navigate to your team's project page on GitHub. You should see a yellow banner that shows the name of your edited branch, as well as how recently it was pushed. In that banner there should be a button that says "Create pull request", so click it.
On the pull request page, you'll be asked to enter a name for your pull request and a description. These are basically just to describe the changes you made. Fill them out however you like, and then hit the "Create pull request" button at the bottom of the form. You'll now be taken to a page which is your newly created pull request!
You can send your teammates the URL of your pull request for them to review. Your teammates can officially approve it via GitHubs' UI, or they can just tell you that they approve it. Either way, once you and your team have agreed that the PR is approved, you can click the "merge" button on the pull request page to integrate your commit fully into the remote repository.
Once you're done with that, don't forget to switch your GitHub Desktop client back to the "master" branch using the branch dropdown!
You did it! You pushed your changes! I always knew you could do this. Give yourself a well deserved pat on the back.
This is your first successful step into the world of git. There's a hell of a lot of things that git can do, and many parts of it may still seem a bit overwhelming, but I hope this tutorial has helped give you a little bit of confidence in your ability to work successfully with git. Happy deving!
Did you like this post? Tell us
Leave a comment
Log in with your itch.io account to leave a comment.
Thanks for the tutorial! I have been thinking of starting to use git, and this helps a lot in understanding it. The only thing I'd add is some screenshots of the steps since I don't know for example what GitHub Desktop looks like (and because I like pictures :D). But still, your explanation of using git was fun and clear to read! 馃挏
What a great resource! Thank you for this :D