GIT [0]
________________________________________________________________________________
Git is a free and open source distributed version control system designed to
handle everything from small to very large projects with speed and efficiency.
[0.0] Index
________________________________________________________________________________
- Git Commands [1.0]
- Example 1: Staying Up-to-Date [2.0]
- Example 2: Squashing Your Latest Commits Into One [3.0]
- Example 3: Writing a new KISS Wiki article [4.0]
- References [5.0]
[1.0] Git Commands
________________________________________________________________________________
New KISS users may have various levels of exposure to git and other forms of
version control systems. The following is intended to be a "quick" reference
sheet of git commands.
+-------------------+----------------------------------------------------------+
| Action | Command |
+-------------------+----------------------------------------------------------+
| | |
| Set Default | $ git config --global user.name "FIRSTNAME LASTNAME" |
| Username | # stored in ~/.gitconfig |
| | |
| Set Default | $ git config --global user.email "EMAIL@EXAMPLE.COM" |
| Email Address | # stored in ~/.gitconfig |
| | |
| Set Default | $ git config --global core.editor vim |
| Text Editor | # stored in ~/.gitconfig |
| | |
| Store User | $ git config credential.helper store |
| Credentials | # credentials saved in ~/.git-credentials |
| | |
| Clone Repo. | $ git clone GIT_URL |
| | |
| Clone Branch | $ git clone GIT_URL -b BRANCH_NAME |
| | |
| Repo. Status | $ git status |
| | |
| Add/Update | $ git add FILE_OR_PATH |
| Project Files | |
| | |
| Apply a patch | $ git apply PATH_FILE |
| | |
| Remove | $ git add FILE_OR_PATH |
| Project Files | |
| | |
| Checkout | $ git checkout BRANCH_NAME |
| | # switch branches or restore working tree files |
| | |
| Commit | $ git commit |
| | # records changes to the repository |
| | |
| Push | $ git push |
| | # updates remote refs along with associated objects |
| | |
| Pull | $ git pull |
| | # fetch and integrate with another repository/branch |
| | |
| Fetch | $ git fetch |
| | # download objects and refs from another repository |
| | |
| Merge | $ git merge |
| | # join two or more development histories together |
| | |
| Rebase | $ git rebase |
| | # reapply commits on top of another base tip |
| | |
+-------------------+----------------------------------------------------------+
[2.0] Example 1: Staying Up-to-Date [1]
________________________________________________________________________________
In a standard setup, you generally have an origin and an upstream remote - the
latter being the gatekeeper of the project or the source of truth to which you
wish to contribute.
First, verify that you have already setup a remote for the upstream repository,
and hopefully an origin too:
+------------------------------------------------------------------------------+
| |
| $ git remote -v |
| |
+------------------------------------------------------------------------------+
If you don't have an upstream you can easily add it with the remote command:
+------------------------------------------------------------------------------+
| |
| $ git remote add upstream UPSTREAM_URL |
| |
+------------------------------------------------------------------------------+
Now you can collect the latest changes of the upstream repository with fetch.
Repeat this every time you want to get updates:
+------------------------------------------------------------------------------+
| |
| $ git fetch upstream |
| |
+------------------------------------------------------------------------------+
Generally, you want to keep your local master branch as a close mirror of the
upstream master and execute any work in feature branches, as they might later
become pull requests.
At this point, it does not matter if you use merge or rebase, as the result
will typically be the same. Let's use merge:
+------------------------------------------------------------------------------+
| |
| $ git checkout master |
| $ git merge upstream/master |
| |
+------------------------------------------------------------------------------+
[3.0] Example 2: Squashing Your Latest Commits Into One [2]
________________________________________________________________________________
With git it’s possible to squash previous commits into one. This is a great way
to group certain changes together before sharing them with others. Let’s say
this is your current git log:
+------------------------------------------------------------------------------+
| |
| * df71a27 - (HEAD feature_x) Updated CSS for new elements (4 minutes ago) |
| * ba9dd9a - Added new elements to page design (15 minutes ago) |
| * f392171 - Added new feature X (1 day ago) |
| * d7322aa - (origin/feature_x) Proof of concept for feature X (3 days ago) |
| |
+------------------------------------------------------------------------------+
You have a branch “feature_x” here. You’ve already pushed d7322aa with the proof
of concept of the new feature X. After that you’ve been working to add new
element to the feature, including some changes in CSS. Now, you want to squash
your last three commits in one to make your history look pretty.
The command to accomplish that is:
+------------------------------------------------------------------------------+
| |
| $ git rebase -i HEAD~3 |
| |
+------------------------------------------------------------------------------+
This will open up your editor with the following:
+------------------------------------------------------------------------------+
| |
| pick f392171 Added new feature X |
| pick ba9dd9a Added new elements to page design |
| pick df71a27 Updated CSS for new elements |
| |
+------------------------------------------------------------------------------+
Now you can tell git what to do with each commit. Let’s keep the commit f392171,
the one were we added our feature. We’ll squash the following two commits into
the first one - leaving us with one clean commit with features X in it,
including the added element and CSS.
Change your file to this:
+------------------------------------------------------------------------------+
| |
| pick f392171 Added new feature X |
| squash ba9dd9a Added new elements to page design |
| squash df71a27 Updated CSS for new elements |
| |
+------------------------------------------------------------------------------+
When done, save and quit your editor. Git will now squash the commits into one.
Note: Do not squash commits that you’ve already shared with others. You are
changing history and it will cause trouble for others.
[4.0] Example 3: Writing a new KISS Wiki article.
________________________________________________________________________________
Note: Specifics of this example are not relevant to this wiki; information about
contributing to this wiki can be found at
https://kisscommunity.bvnf.space/website/.
Note: The method described below requires a GitHub user account. If you do not
have a GitHub user account or do not wish to create one, you can still
submit your articles or ideas directly to dylan@k1ss.org.
Lets say you are interested in writing a new article for the KISS Wiki. The
process is fairly straight forward!
Begin by first creating a fork of the KISS Wiki repository. One way to do this
is from a web browser by going to the https://github.com/kiss-community/wiki
page, clicking the "Fork" button in the upper right corner of the page. Doing so
should create a copy of the KISS Wiki repository on your user account (e.g.
https://github.com/USERNAME/wiki).
Clone the forked repository to your PC with the following command. Remember to
replace USERNAME with your actual GitHub username.
+------------------------------------------------------------------------------+
| |
| $ git clone https://github.com/USERNAME/wiki.git |
| |
+------------------------------------------------------------------------------+
Once cloned to your PC, navigate to the wiki directory:
+------------------------------------------------------------------------------+
| |
| $ cd wiki |
| |
+------------------------------------------------------------------------------+
Add your new article in this directory per the #/wiki/help/adding-a-page
guidelines. Once you are ready to publish your newly created article, you need
to add/update your forked repository. From the main wiki directory, you can
check the status of all changes or newly created files:
+------------------------------------------------------------------------------+
| |
| $ git status |
| |
+------------------------------------------------------------------------------+
Using the output of command above, update/add the new files your forked
repository that are ready to be published:
+------------------------------------------------------------------------------+
| |
| $ git add FILE_NAME1 FILE_NAME |
| |
+------------------------------------------------------------------------------+
Alternatively, you can add ALL newly updated/created files in a single command:
+------------------------------------------------------------------------------+
| |
| $ git add * |
| |
+------------------------------------------------------------------------------+
Next, you will commit your changes.
+------------------------------------------------------------------------------+
| |
| $ git commit -m "YOUR_COMMIT_MSG" |
| |
+------------------------------------------------------------------------------+
Replace YOUR_COMMIT_MSG with a short description of change(s) or the new article
(i.e. "git: new article" or "git: add new git example").
At this point you are ready to push your changes to the GitHub server with the
following command.
+------------------------------------------------------------------------------+
| |
| $ git push |
| |
+------------------------------------------------------------------------------+
Upon doing so, you will be prompted to enter your GitHub user credentials. Once
entered, the latest changes will be uploaded to your forked Wiki repository
on GitHub.
The last step is to initiate a Pull Request (PR). A PR can be initiated via a
web browser by going to the https://github.com/USERNAME/wiki page and pressing
the "New pull request" button near the top of the page. In the Title field,
enter the reason for initiating a PR (i.e. "git: new article") and press the
"Create pull request" button.
Note: Pay attention to which branch is being merged into the master branch of
the repository :kiss-community/wiki".
[5.0] References
________________________________________________________________________________
[0] https://git-scm.com
[1] https://www.atlassian.com/git/tutorials/git-forks-and-upstreams
[2] https://www.devroom.io/2011/07/05/git-squash-your-latests-commits-into-one/