If you are working on any project that involves text documents (source code, html, css, markdown, mediawiki format, latex, or any other text based formatting language), then you are going to need to know Git. It is not just for source code for huge projects like ebay, but it can also be used for websites like jackpot casinos . You can even host your website on GitHub, but that is beyond the scope of this article.
This article contains my personal notes that I wrote while I worked through the YouTube video “Git and GitHub for Beginners Tutorial” by Kevin Stratvert. The actual video is 45 minutes, but in reality, it took me around 8 hours to complete the video (2 hours per day for 4 days).
I was determined to actually do everything that the was done in the video, and when a topic interested me and I wanted to learn more, I took a break from the video and went on a tangent. Although there were a few things in that video that did not match the most recent version of Git v2.39, for the most part, it was a very good tutorial.
My notes do not include:
- Setup of Git in my local environment of the most recent version of Git v2.39.
- Installing git-prompt.sh. When you cd into a directory that is controlled by Git, the command prompt changes to show this, along with some Git information codes.
- Creating my Github account and learning the website Gui. The GitHub GUI is self explainatory.
- Using Git CLI, “gh”. This was not covered in the video tutorial.
My overall thoughts of Git, GitHub, etc.
Git and GitHub are both worth learning, but GitHub is just one option of an online Git repository. As for how to setup your Git working environment, I would personally recommend using “git flow”. That was also not covered in the video tutorial.
References
- Video Tutorial “Git and GitHub for Beginners” by Kevin Stratvert: https://www.youtube.com/watch?v=tRZGeaHPoaw
- Example files from the video tutorial: https://onedrive.live.com/?authkey=%21AJdw967%5FoljMamM&id=B09F9559F6A16B6C%2178117&cid=B09F9559F6A16B6C
Initialize a project and git status
It is assumed by this point, you have already downloaded some example files (or created at least the README.md file).
$ git init # Initialize the repository.
$ git add index.htm # Add all of the files to the default repository (main)
$ git status # Shows our git status (branch and info about the files)
$ vim .gitignore # create our .gitignore file, we added *.txt, so “Salaries.txt” will be ignored.
$ git add –all # Add all files to the staging area. Salaries.txt is removed from our cache.
$ git status # we no longer see “Salaries.txt” in our list of files.
$ git status –short # Show status with abbreviations instead of the full descriptive words. “A” instead of “add”.
Understanding your command prompt in a Git directory
By this point, our command prompt (with “git-prompt.sh” installed) looks like this:
melissa@linux:~/Projects/git-tutorial (main *+%) $
- Our directory is “~/Projects/git-tutorial”
- Our branch is “main”
- We have files that are unstaged “*”.
- We have files that are staged “+”
- We have files that are untracked “%
Track and untrack files in git
# Add a file to gir, stage a file, track a file.
$ git add –all # Salaries.txt is removed from our cache.
$ git status # we no longer see “Salaries.txt” in our list of files.
$ git status –short # Show status with abbreviations instead of the full descriptive words. “A” instead of “add”.
# Remove a file, unstage a file, to untrack a file
# git rm –cached
$ git rm –cached index.htm
$ git status
# Other types of “git rm –cached
$ git rm –cached . # Removes all files in the current directory from git tracking.
$ git rm -r –cached . # Removes all files recursively from git tracking.
$ git rm Documentation/\*.txt # Removed all “.txt” files from the “Documentation” directory.
Commit changes to git
$ git commit -m “First commit — committing all files to the repository”
$ git status
Change files and view differences
# We have modified index.htm
$ vim index.htm
$ git status
# See differences. Red is text that we removed. Green is text we added.
$ git diff # We can see our differences
$ git add index.htm # We are adding our new changes to the staging area (not yet committed).
What is the working tree, the staging area, and the commit area?
Staging is a place where your files sit until you are ready to commit them.
It is like a holding pen until you are ready to commit the changes. This will allow you to add a file.
Work on another file. Then commit both files as one group commit. In other words, all of the small changes
were part of the small sub-item of a feature or bug fix.
- The working tree — the files on your file system that correspond with the repository.
- The staging area — the holding pen until you are ready to commit the changes.
- The environment where you commit things — they are saved for the history books with a formal label.
What if I want to remove items from the staging area?
If we use the “git restore –staged index.htm” our changes will be removed from the staging area and returned
to our working directory. This is different than “git rm –cached index.htm”, which would remove the whole file
from the staging area, instead of just the most recent changes.
If we do “git status”, we will see that index.htm is no longer in the staging area and if we commit all of the files
in the staging area, at this point, the changes to “index.htm” would not be committed.
Bypassing staging and committing to git
$ git commit -a # Git will notice that the file has been removed and update the index.
Delete files and restore files
$ git rm –cached mybadfile.htm # unstage and remove paths only from the index. Working tree files,
# whether modified or not, will be left alone. If you do not want it
# readded the next time you do “git add -A”, you need to add the filename
# to .gitignore.
$ rm mybadfile2.htm # Filesystem version of removing a file.
$ git add -A # Git will notice which files have been added, modified, or deleted and update the
# index correctly.
# Restoring the file
$ git restore mybadfile.htm # Restore content in the index to the working tree
$ git restore –staged mybadfile2.htm # Restore content in the index to the working tree
$ git restore –worktree mybadfile3.htm # Restore files from commit to both the working tree and the index
- (Green text) — We modified “index.htm” and we added it to our staging area. It is listed under “Changes to be committed” with green text because we are ready to commit and things will work as expected.
2. (Red text) — We modified “index.htm”, and we either did not add anything to our staging area, or else we added and then restored the cache from our staging area. This means that we are not ready to commit, because our staging area does not match our working directory.
What if I want to commit only some of the files I have changed?
Let’s say that you changed 6 files, but you only want to commit 6 of them. You would put the three files that you want to commit into the staging area, and then commit them. The other three files that were modified, but not staged, will not be committed.
How can I commit my changes without first staging my changes? Plus some other commands
# Commit without first staging.
$ git commit -a -m “This is a commit without first staging”
$ git status
# Remove a file from both git and the working directory. The delete file is stagged, but not committed.
$ git rm secret-recipe.htm
$ git status
# To get back our secret-recipe.htm
$ git reset HEAD~ –hard
$ git status
Rename a file or move a file
# Rename our logo file
$ git mv KCC-Logo.png primary-logo.png
$ git status
$ git commit -m “Changed KCC-Logo.png to primary-logo.png”
$ git status
View commit history with git log
# To see all of the changes that we have done
$ git log
# To see the log with just one line per log entry
# We do not see the Author or the date of the commit in a oneline log display
$ git log –oneline
# Change the text of a commit comment without having to “recommit” the file
$ git commit -m “Changed file name to primary-logo.png” –amend
$ git log –oneline
# To see what exactly was changed. The log is being displayed through “more”, so you
# will need to use the up and down arrows to move around in the log. Type “q” to quit
# and return to the command prompt.
$ git log -p
Amend commit
$ git commit -m “Renamed file to primary-logo.png” –amend
$ git log –oneline
View changes in commits
Show differences in the changes. Use the up and down arrows to view the log. It is “more” to paginate the text.
$ git log -p
Reset to the previous commit
$ git log –oneline
$ git reset 8231c4c # the “8231c4c” is the hashtag that is associated with each change.
Rebase git repository, combine and/or modify commits
When you have a bunch of small commits and you want to combine them into one commit, you would use “rebase”.
$ git rebase -i –root # The process of moving or combining a sequence of commits to a new base commit.
# When you do “rebase” an editor appears and there are a bunch of options to choose from
# do determine what you want to do with the commits.
There are so many options with “rebase” that it can be its own video.
Branches
$ git branch FixTemp
$ git branch # Show us all of the branches and which branch we are on.
$ git status # Only shows us information about the branch we are current working on, “main” (in this example)
$ git switch FixTemp
$ git status # We switched to the “FixTemp” branch, and “git status” confirms this.
# We can also see from our command prompt that we are working in the “FixTemp” branch.
# That is assuming that you copied “.git-prompt.sh” to your home directory and called it from “.bashrc”
$ git branch # Shows both branches and “FixTemp” is the current branch we are working with.
At this point, the files we see in the Working Directory are the files from the “FixTemp” branch, which at this point is
exactly the same as what is in “main” (since we have currently not done any changes to any files).
$ vim secret-recipe.htm
$ git status # See “secret-recipe.htm” has been modified.
$ more secret-recipe.htm # We see temp is 375
$ git switch main
$ more secret-recipe.htm # We see temp is still 500
Now we need to merge the changes from FixTemp into the main branch.
Merge branches
$ git switch main # Need to be in the main branch, the final branch of the merge
$ git merge -m “Merge FixTemp into the main branch” FixTemp # FixTemp is going to merged into main
$ git more secret-recipe.htm # We see our changes (temp is now 375 and not 500)
Delete branch
At this point, the changes have been merged. The tutorial says we can now delete this branch, but
from my experience, the branch should not be deleted until it has been regression tested (to make sure that nothing)
that was changed in “main” affected your fix and nothing in your fix, broke something in main. But that is just being
extra careful.
$ git branch # You will see two branches,”main” and “FixTemp”
$ git branch -d FixTemp # FixTemp branch is deleted.
$ git branch # Now you will only see “main”
Typical Git flow
$ git switch -c UpdateText # We are switching branches and creating a new branch in the same command.
$ git branch # We see two branches and that we are in “UpdateText”. We can also see this
# in our command prompt.
$ vim index.htm # Edit index.htm file. Changed “finest” to “best”
$ git commit -a -m “Update index text” # Skipped staging and just commited our simple change. For larger commits that involve
# multiple files and multiple changes, you always want to stage before committing.
$ git switch main # Changed back to the main branch.
$ vim index.htm # We are going to change the text in main also (both branches will have changes on the same fjile.)
# Change “finest” to “most amazing”. Same file changed in different ways in two different branches.
$ git commit -a -m “Update index text” # Changes to the “main” branch are committed.
$ git merge -m “Merge UpdateText into the main branch” UpdateText # Trying to merging UpdateText into “main”
# We have a conflict, because the same file was changed in both branches. So we need to do a manual merge (human intervention)
# If you look at the command prompt, you will see that we are now working in a subbranch of main called “merge”. Once we make our
# manual merge and do a commit, this subbranch of “main” called “merge” will automatically disappear and we will just be in our
# “main” branch.
$ vim index.htm # This is the auto merged “index.htm” file. We see the changes from both files merged into one file.
# Now we need to manually look at each difference and determine which one is the correct one and
# which one is the incorrect one?
$ git commit -a -m “update text on index”
$ git branch # We only see “main” and “UpdateText”
# If we now want to delete the branch “UpdateText”
$ git branch -d FixTemp
$ git branch
Reflection on the tutorial so far.
This is a great tutorial, but if you use the gitflow philosphy, the branch you will do most of your merges into will be “dev”, not “main”.
Branch “main” should only be merged into for formal releases to the public. If the public is not ready for the change, then it does
not belong in “main”.
Every commit in “main” has to have a formal version number. The general standard that a lot of programming groups follow is
[major number].[minor number].[maintenance number].[build number]When should I update my “major release number”?
- When your API changes
- When your database structure changes
- When you are doing a LTS (long term support) release. Most people assume that the LTS release will contain database changes and API changes.
How to specify “composer” version numbers (used in MediaWiki json files, for example)
{
“requires”: {
“MediaWiki”: “>= 1.27.0”,
“extensions”: {
“FooBar”: “*”,
“Baz”: “>= 1.2.3”
},
“platform”: {
“php”: “>= 7.1”,
“ext-curl”: “*”
}
}
}
# Display all of our “tags”, aka. version numbers.
$ git tag
How can we setup the different version numbers in composer format (a common versioning number standard)? The prefix “v” is automatically removed.
- 1.1 # Only version 1.1, and nothing else
- >=1.1 <2.0 # >= to version 1.1, but less than version 2.0
- ~4.0 # Any version that beings with 4.
List of version branches
- v1.0 # Major release 1
- v1.0.1 # Major release 1 and maint release 1
- v1.0.2 # Major release 2 and maint release 2
- v1.1-BETA # Major release 1 and minor release 1, beta release (alpha is first)
- v1.1-RC1 # Release candidate 1 for version 1.1
- v1.1-RC2 # Release candidate 2 for version 1.1
- v1.1 # Major release 1 and minor release 1
- v1.1.1 # Major release 1, minor release 1, and maint release 1
- v2.0-BETA # Major release 2, beta release
- v2.0-RC1 # Major release 2, release candidate 1
- v2.0 # Major release 2
- v2.0.1 # Major release 2, maint release 1
- v2.0.2 # Major release 2, maint release 2
- v1.1-dev # Major release 1, minor release 1, dev branch
The following version suffixes are standard:
- -dev # Development release
- -alpha # Alpha release (first try at releasing to the public, all features added, but not all bugs fixed.)
- -beta # Beta release (second try at releasing to the public, think all bugs are fixed, but a guarantee)
- -RC # Ready for release (but still assume that there are some bugs)
- -stable # There should not be any major bugs.
Version ranges
- > # Less than the version number
- >= # Less than or equal to the version number
- < # Greater than the version number
- <= # Greater than or equal to the version number
- != # Does not equal the version number Multiple version numbers
- Separated by a space ( ) or a comma (,) will be treated as logical AND
- Separated by a double pipe (||) will be treated as a logical OR
- Logical AND has higher precedence than logical OR. Do not use unbounded ranges, especially for extensions and skins, because you do not know if the changes to the core created unexpected bugs in your code (eg. databases changed, API hooks became deprecated). An unbounded range is a range that goes off into infinity on one or both sides
- >=1.0 # Unbounded on the upper side
- >=1.0 <1.1 || >=1.2 # Unbounded on the upper side.
- 1.0 – 2.0 # Problem is that it actually equals >=1.0.0 <2.1, and that is not usually what people want.
- >=1.0 <2.0 # Bounded on both sides. Use this to indicate you want all 1.x version, up until v2.0, but not including v2.0.
- 1.0.* # Equals >=1.0 <1.1
Tilde range version
A common usage would be to mark the minimum minor version you depend on, like ~1.2 (which allows anything up to, but not including, 2.0). Since in theory there should be no backward compatibility breaks until 2.0, that works well. Another way of looking at it is that using ~ specifies a minimum version, but allows the last digit specified to go up.
- ~1.2 # Equals >=1.2 <2.0.0
- ~1.2.3 # Equals >=1.2.3 <1.3.0 If you are working on a project like a MediaWiki extension and want to make sure your extensions work for every LTS version, this versioning method will not work due to the way the MediaWiki core versioning numbers are handled.
Carat version numbers
- ^1.23 # Equals >=1.2.3 <2.0.0, none of the releases before v2.0 should break backward compatibility.
About GitHub (online git repository)
- Register on GitHub.com
- Create a personal token: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
- Your login and token information will be stored in ~/.gitsomeconfig
What you can do on GitHub
- Cloud repository (store your code online)
- Manage your project
- Setup Kanban boards – A Kanban board can be as simple as a three-column chart — Tasks, Progress, and Done. It is a method of project management.
- Track issues
- Assign features and bugs to different people
GitHub is a whole project management and feature tracking / bug tracking system. It is not just a web GUI version of git (although it does have that).
Set up GitHub account and configure your github account
- Setup a git account: github.com (click on Sign up and follow the instructions)
- Create your profile repository on GitHub — Once you have created your GitHub account, you need to create some repositories.
There is a special repository that is the same exact name as your username. For example, if your username is “ilovegit”, this special repository will be named “ilovegit”. When the user selects your URL, this is what is displayed for the user:
- https://github.com/ilovegit
The page that appears is divided into two columns. The thinner left column is your profile. It displays …
- Profile picture (optional)
- Your name (optional)
- Your username (optional)
- Your work (optional)
- Your local time (optional)
- Your web address (optional)
- Your Twitter handle (optional)
The main right column is a display of your README.md file that is stored at “https://github.com/ilovegit/README.md
The suffix “md” stands for markdown. Your README.md can be stored as either HTML or Markdown. The file can be as simple or as complex
as you want it to be.
Create a new repository on GitHub
Use the GitHub GUI to create a new repository on GitHub.
I named my repository “git-tutorial”, because that is the name that I used for my local repository.
Just follow the prompts. It is pretty straightforward. If you do not mind other people seeing your work, mark your repository as “public”. If you do not want others to see your work, mark your repository as “private”.
Select a default README.md. You can modify this later, but every project should have a README.md file, so a reader knows (in English terms) what the repository is for. The README.md file contains the following info (at a minimum):
- What is the project about in simple English terms.
- How to install the code.
- How to run the code (bare bones basic running)
- Link to more detailed documentation
- Link to screenshots of your program.
- Link to a video, if you have one.
- Status of the project (in development, in testing, stable, no longer maintained)
- Contact info
You also need to specify if the items are copyrighted or have an open license. For most of my projects, I personally use the “MIT License”.
Also, include a “.gitignore” file even if right now you think it will remain blank.
There are also instructions for two options:
- Creating a repository on your local computer (if a repository does not already exist on your local computer).
2. Linking to an existing repository on your local computer. (Option we will be using, “~/Projects/git-tutorial” repository)
Push local repo to GitHub
$ git remote -v # See if any remote repositories are associated with this local repository.
$ git remote remove origin # removes online repository associated with “origin” (default name used for remote repositories)
$ git remote add origin https://github.com/ilovegit/git-tutorial
$ git push -u origin main # only pushes your “main” branch, even if you have other branches.
# At this point you will see two prompts:
# username (GitHub username)
# password (GitHub token for your repository, not your github password).
$ git push -all # pushes all branches to origin (github)
Now your local Git is in synch with your remote repository.
But these tutorial notes are not going to go into details about fixing that.
In your local git configuration settings, the “user.email” should match the email that you used to create your GitHub account.
The “user.name” does not need to match.
Create an official release
# select “create a new release” on the right side of your repository area.
# Choose a tag: “v1.0.0” (we do not need the word ‘release’)
# Click on “publish Release”
# We now have v1.0.0 available for download.
# Users can now download the offical release in .zip or .gz format (zip or tar)
$ git fetch # Gets the modified code from “origin” (github) and places it in our local “git”
$ git merge # Merged the changes from “origin” into our local “git”
$ git pull # This combines the above two commands.
And now we are done
Actually, “It is not the end; it is not the beginning of the end. But it is the end of the beginning.”. (Quote from Winston Churchill and the movie “Millennium”)
“Wannabe internet buff. Future teen idol. Hardcore zombie guru. Gamer. Avid creator. Entrepreneur. Bacon ninja.”
