Back: Your First git Repo |
Main Table Of Contents | Next: Glossary |
|---|
To interact with git, it is important to make sure that you are in the directory of the repo. Any directory that has a .git folder is a directory that is being version-controlled by git.
PRO-TIP:
If you are ever confused by something in git, you can type git help [command] then hit enter. It will bring up an explanation. https://git-scm.com/book/en/v2/Getting-Started-Getting-Help
- Interacting With
git, And How To Contribute Your Work To The Repo - PRACTICING BY YOURSELF
Enter the directory where your git project is.
You do this by typing in the command line:
cd [directory name]Remember to put a space between cd and the directory name. Then hit Enter on your keyboard.
It should appear this way:
| Back To Table Of Contents |
|---|
It is very important not to make any changes directly in the master branch, or else it will cause conflicts and errors for the project or for the rest of the team who is working together on this repo.
To make a new branch, type in the command line:
git checkout -b [name of your branch]Then hit Enter on your keyboard.
You will notice that the cyan/light blue words in the parentheses have changed from Master to the name of your current branch that you are on. This means that you have moved from the master branch to this branch.
.PNG
?raw=true "git checkout -b")
Always check the cyan/light blue words in the parentheses to make sure which branch you are on.
If you want to check what branches exist in your local repo, in the command line, type git branch
This will show a list of branches in your local machine. The branch that you are on has an asterisk in front of its name.
.PNG
?raw=true "git checkout -b")
Branch names cannot contain spaces.
Remember our friend "tab-completion"? It works for these git commands too! ^-^
If you are ever confused by something in git, you can type git help [command] then hit enter. It will bring up an explanation. https://git-scm.com/book/en/v2/Getting-Started-Getting-Help
How do I name my branch? The general rule of thumb is that the branch describes what the work is doing. The important thing is that the branch names are understandable when anyone reads it, so they know exactly what is happening in it. But aside from that, it really depends on the team that you are working with. The second-most-important thing about naming conventions is that it is consistent with everything else in the project.
There are 3 styles of branching or branch-naming that I've seen commonly done (but there are probably others), and they are: feature branch = a branch for each new feature, and named for each feature (usually in larger, long term projects. team-mate branch = a branch for each team-mate, and named for each team-mate (usually in smaller projects, like game jams). combination of both = the branch name has the team-mate's name, followed by the name of the feature they are working on.
Honestly, a lot of the details of these things are opinions. As long as a branch name is understandable and consistent with the team's naming conventions, then it's OK.
When is it time to make a new branch? For certain, it's when newly-cloning a repo, just to make sure that the master branch will not get messed up. But aside from that, it's like the naming conventions. It depends on the team, so it's important to consult your team and follow the style-guide if one exists.
| Back To Table Of Contents |
|---|
After Step 2 and before Step 4, you don't need to make any changes to your workflow.
| Back To Table Of Contents |
|---|
When your work is in a good place, and it's a good time to save, now is probably a good time to add your work to version control.
If you want to see what files have been changed, type git status in the command line.
To see what changed in a file, use git diff:
To "stage" or to prepare files for version-control, type in the command line:
git add [name of the file to add]This is for each file that needs to be added.
![git add [a_single_file] example](/BerniceChua/BeginnersComprehensiveGitAndGitLFS/blob/master/images/git_add_a_single_file.PNG?raw=true "`git add [a_single_file]` example")
To add all files in the current directory, it is:
git add .(that last character is a period or dot.)
To add a directory:
git add [directory name/](that's a period or dot.)
[screenshot]
To add ALL changed files:
git add -A[screenshot coming soon]
Although if a lot of changes have been made, it's better not to do this unless all the changes are related, or else your commit message will be very long.
After running git add, this is the part that backs up your work on your local machine.
To do this, type in the command line:
git commit -m "[Your commit message.]"Wherein:
| Command | Meaning |
|---|---|
git commit |
the command that makes the backup |
-m |
the flag that says make a commit message. This is important, because it's for describing what work was done. It's for labelling the "snapshot". |
"[Your commit message.]" |
the description of what changes were made. It's important to surround it with double-quotes. |
[screenshot]
Each git commit can contain multiple git adds, as long as they are related or similar.
If git commit is written WITHOUT -m "[Your commit message.]", git bash will look for the default text editor that you installed, so that a commit message can be written. All commits need messages. (This is why git bash asked for a default text editor during the first-time-setup.)
The convention for writing commit messages is an imperative sentence.
Examples:
- "Revert the last commit, which broke the build."
- "Corrected typo in NPC's dialogue."
- "Increase border widths for game over UI pane."
- "Change lighting to baked, to solve framerate drops."
- "Replace 3D model of player from prototype to our customized one."
- "Add code to make objects invisible if it's between the camera and the player."
Read these for explanations and for more examples:
- https://www.freecodecamp.org/news/writing-good-commit-messages-a-practical-guide/
- https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53
Commit messages need to be clear, so that referring to it later (either manually or with git log, more on this later), people can find things easily, and know exactly what each commit has changed.
When git saves changes, it doesn't actually save the entire document. It just saves a "differential" or a "diff", which is the snapshot of what got changed. For example, the "diff" of when a file is first created is the entire file; the diff of an edit to that file is just the changes to the file. This is how git can back up lots of things while still allowing users to go back and forth in its timeline, and not take up too much space.
Keep doing steps 4.1 and 4.2 for each new feature
| Back To Table Of Contents |
|---|
When you are satisfied enough with your work to share it with everyone in the team, it is time to push changes to the remote repo.
As a precaution, it's important to get changes from the remote repo first, before pushing your changes. To get changes from the remote repo, type in the command line:
git pull origin masterThen hit the Enter key on your keyboard.
Explanation:
git pullis the command that pulls changes from the remote repo.originis the shortcut for the URL of the remote repo.masteris the name of the main branch. It could be called something else, but the default ismaster.
To check what is set as the remote repo, type in the command line:
git remote -vThen hit Enter on your keyboard.
If there is nothing to update, it will say Already up to date., and it will look like this:
If there are changes, it will look like this:
But there's sometimes a case where git bash will bring up the default text editor after pulling from the remote repo. This is the other reason why git bash asks for a default text editor. The reason for this is for writing a comment about what is being merged. Usually a message like Sync with remote repo. will suffice, unless major changes need to be made.
To Do: complete Step 5.1.2
This step actually prepares the changes to be shared to the remote repo.
To "stage" or to prepare files for version-control, type in the command line:
git push origin [branch name]This is for each file that needs to be added.
In the remote repo's website:
GitHub version:
| Back To Table Of Contents |
|---|
The way this step is implemented depends on the conventions that the team is following. There are some teams where the person to merge the changes to the master branch would be the person who reviews the changes. There are other teams where the person to merge the changes is the person who made them, after the changes have been reviewed and deemed all clear/all right.
Either way, these are the steps for whoever does the merging:
Make sure to check the changes:
Red background means they were deletions:
Green background means they were additions:
Optionally, add a comment to clarify each change if there were a lot of changes:
(see this for an example of comments: #8)
Make sure that everything is ok first before clicking the merge button:
Screenshot of when merge was completed:
| Back To Table Of Contents |
|---|
Go back to the main page of the remote repo to see the changes.
Also, don't forget to git pull origin master in your local repo (both in the branch that you're working out of, and also in the master branch). This is done so that everything is updated to the same state everywhere.
| Back To Table Of Contents |
|---|
| Back To Table Of Contents |
|---|
Why are there so many steps? Even for just for backing up a file locally? Then there are even so many steps for backing up to the server??
The first time I used git, I was also confused by this. But I learned that there are good reasons for all this. It's mainly to ensure that anything that's done is reversible if mistakes are caught early, and easily fixable.
An easy way to think of this entire process is the same as putting stuff into a delivery van.
git add is the equivalent of putting stuff into a box.
git commit is like labelling a box and marking it for putting into the delivery van; saying that it is ready for delivery.
git push is like putting those labelled boxes into the delivery van
Going to the remote repo and making the pull request is the equivalent of sending stuff to their destination.
You can use this analogy to explain git to others, just give credit to me for where you found this analogy.
| Back To Table Of Contents |
|---|
Practice more to get comfortable using git.
If you want to practice more by yourself, feel free to clone this repo and mess around with making new branches, switching branches, making changes to files or adding files, making adds and commits, making pull requests, and anything else.
-
"Learn git Branching""
-
Katacoda
- https://www.katacoda.com/courses/git & https://www.katacoda.com/courses/git/playground
- Free to make an account, and free to use
-
Git Exercises
-
Visualizing git
- http://git-school.github.io/visualizing-git/
- Explore how Git commands affect the structure of a repository within your web browser with a free explore mode, and some constructed scenarios.
| Back To Table Of Contents |
|---|
Back: Your First git Repo |
Main Table Of Contents | Next: Glossary |
|---|