Installation
Refer to Git – Downloads.
Configuration
Git categorizes configuration files based on their scope, with two commonly used levels:
- Global configuration file for the current user, which applies to all repositories operated by that user on the system.
- Repository-specific configuration file.
When multiple configuration files set the same option, the local settings automatically override the global settings. Therefore, if you need to apply specific settings to a repository, simply change the settings for that repository without affecting the global settings.
To modify the configuration files, use the git config command.
Setting User Information
After installing Git, the first thing to do is set your username and email. This information is used in each commit.
$ git config --global user.name "example"
$ git config --global user.email [email protected]
The username and email provided here are for demonstration purposes. When configuring based on this page, remember to replace the username and email with your own information.
The --global flag indicates that the global configuration is being modified, meaning the settings apply to all repositories under the current user. If the --global option is omitted, the configuration file for the current repository will be modified.
To modify the specific settings for a particular repository, simply run the command without the --global flag within that repository.
Configuring the Editor
$ git config --global core.editor emacs
Running the above command changes the editor to Emacs.
On Windows, the default editor for Git can be chosen during Git installation (as mentioned earlier). To change it later, enter the command above in Git Bash, replace the editor name with the absolute path of your preferred editor, and run the command.
Displaying Configuration
Use the git config -l command to list all currently set configuration parameters. Use git config --global -l to list all global configurations.
Basic Repository Operations
Creating a New Git Repository
Creating a new Git repository is simple. Enter the following command in the folder where you want to create the repository:
$ git init
Git will create a .git folder in the current directory, and a repository is created.
To clone a repository to your computer (e.g., to copy example‘s code locally for editing), use the git clone command.
$ git clone https://github.com/example/example
“Remote Repository Link”
The repository link provided here is an HTTP(S) link, meaning we are connecting to the remote repository using HTTP(S).
In fact, there are multiple ways to connect to a remote repository. Among them, using SSH to connect to a remote repository is more convenient and secure. We will briefly introduce the method of using SSH to connect to a remote repository in the "Managing Remote Repositories" section.
The content of the cloned repository will be stored in a new folder named after the repository in the current directory. In this example, a new folder named OI-wiki will appear in the current directory.
Tracking Files
After making changes to the files in the repository, these changes need to be included in version control.
Use the git status command to check the status of the files in the current repository.
For example, after adding a README.md file to an empty repository, the effect of executing the git status command is as follows:
$ git status
On branch master
No commits yet
Untracked files:
(use "git add <file>..." to include in what will be committed)
README.md
nothing added to commit but untracked files present (use "git add" to track)
The “Untracked files” refer to files that Git has not yet included in version tracking. If a file is not included in version tracking, changes to that file will not be recorded by Git.
Execute the git add <file> command to include the specified file in version tracking.
$ git add README.md # Include this file in version tracking
$ git status
On branch master
No commits yet
Changes to be committed:
(use "git rm --cached <file>..." to unstage)
new file: README.md
At this point, README.md is included in version tracking and placed in the staging area. The next step is to commit this change using the git commit command.
But before that, let’s make some changes to README.md.
$ vim README.md # Make some changes
$ git status
On branch master
No commits yet
Changes to be committed:
(use "git rm --cached <file>..." to unstage)
new file: README.md
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore -- <file>..." to discard changes in working directory)
modified: README.md
You will find that README.md is in both the staging area and the working directory. Actually, the staging area refers to changes, not files. Therefore, the previous change to README.md has been included in the staging area, but the subsequent change has not. If you execute the git commit command at this time, only the changes in the staging area will be committed, and the changes in the working directory will not be committed.
Git provides a hint: execute git add README.md to include the changes in the working directory in the staging area.
“Adding All Changes to the Staging Area at Once”
The git add command will include changes to the specified file in the staging area.
In most cases, users prefer to include all changes in the staging area at once. You can use the `git add -A` command. This command will include all changes (including untracked files, excluding ignored files) in the staging area.
If you only want to update tracked files and not include untracked files in the staging area, you can use `git add -u`.
“Ignoring Files”
Sometimes we do not want to include certain files (such as executable files) in version tracking. You can create a .gitignore file in the root directory of the repository and list the files you want to ignore. Git will not include these files in version tracking.
For example, `*.exe` will automatically ignore all files with the `.exe` extension in the repository.
Now include the changes in the working directory in the staging area and commit all changes.
$ git add README.md
$ git commit # An editor page will pop up, and you need to write the commit message
[master (root-commit) f992763] initial commit
1 file changed, 2 insertions(+)
create mode 100644 README.md
Now pay attention to the commit information of this commit.
master indicates that the current branch is master (the issue of branches will be introduced in detail later), b13c84e indicates the first few digits of the SHA-1 checksum of this commit, and the rest is the commit information of this commit.
It is important to note the SHA-1 checksum here. Each checksum corresponds to a snapshot of the repository at a certain point in time. Using this feature, we can access the snapshot of the repository at a historical point in time and make changes to that snapshot.
The following two lines detail the file changes involved in this update.
Additionally, the commit process can be simplified using several parameters:
-a: Include all changes to tracked files in the staging area before committing. Note that untracked files (newly created files) will not be automatically included in the staging area and need to be manually added using thegit addcommand.-m: This parameter followed by the commit message indicates that the changes will be committed with the provided message. For example,git commit -m "fix: typo"will create a commit with the titlefix: typo.
Viewing Commit History
Use the git log command to view the commit history of the repository.
You can see that the commit history records the SHA-1 checksum of each commit, the author of the commit, the commit time, and the commit message.
$ git log
commit ae9dd3768a405b348bc6170c7acb8b6cb5fe333e (HEAD -> master)
Author: example <[email protected]>
Date: Sun Sep 13 00:30:18 2022 +1000
feat: update README.md
commit f99276362a3c260d439364c505a7a06859f34bf9
Author: example <[email protected]>
Date: Sun Sep 13 00:06:07 2022 +1000
initial commit
Branch Management
Why is branch management needed in version control? There are mainly two reasons:
- Making changes directly to the main branch not only confuses the history but can also lead to some dangerous consequences.
- Branches allow us to focus on the current work. If we need to complete two different tasks, we can create two branches, and the work in the two branches will not interfere with each other.
In Git, a branch is essentially a pointer to a specific snapshot. Each time a commit is made, Git creates a snapshot of the commit and moves the branch pointer to that snapshot.
Additionally, there is a HEAD pointer that points to the current branch.
The process of switching branches is essentially changing the HEAD pointer to point to a different
Sure, let me complete the translation for you.
The process of switching branches is essentially changing the HEAD pointer to point to a different branch. During this process, Git automatically updates the files to ensure that the state of the repository matches the snapshot pointed to by the target branch.
Creating a Branch
Use the git branch command to create a branch, git switch to switch branches, and git switch -c to create a branch and switch to it.
$ git switch -c dev # Create a new branch called dev and switch to it
Switched to branch 'dev'
$ git branch # View the list of branches
master
* dev
The asterisk in front of dev indicates that the current branch of the repository is dev, and the following changes will be recorded on this branch.
Try creating a new file aplusb.cpp.
$ vim aplusb.cpp
$ git add aplusb.cpp
$ git commit -m "feat: add A+B Problem code"
[dev 5da093b] feat: add A+B Problem code
1 file changed, 7 insertions(+)
create mode 100644 aplusb.cpp
Now switch back to the master branch. At this point, the aplusb.cpp file is not present in the folder, and everything returns to the state it was in when the dev branch was created. You can now continue working on other tasks on the master branch.
$ git switch master
Switched to branch 'master'
$ vim README.md # Make some changes to README
$ git commit -a -m "feat: update README.md"
[master 5ca15f0] feat: update README.md
1 file changed, 1 insertion(+), 1 deletion(-)
Below is a diagram explaining the above operations.
The master branch is highlighted in red, indicating that it is the current branch (i.e., where the HEAD is pointing).
- Initially,
masterpoints to theae9dd37snapshot. - Next, a new
devbranch was created at the position wheremasterwas located, which initially points to the same location asmaster. - Some changes were made on the
devbranch (creatingaplusb.cpp), and a commit was made. After this commit, thedevbranch points to the5da093bsnapshot. - After switching back to the
masterbranch, since themasterbranch still points toae9dd37, theaplusb.cppfile is not created yet, so it does not exist in the repository. - Further changes were made on the
masterbranch (updatingREADME.md), and a commit was made. Themasterbranch points to the5ca15f0snapshot.
Merging Branches
When work on a branch is complete, it can be merged into another branch.
Continuing from the example above, the work on the dev branch is complete. You can merge the branch into the current branch (master) using the git merge command:
$ git merge dev
Merge made by the 'recursive' strategy.
aplusb.cpp | 7 +++++++
1 file changed, 7 insertions(+)
create mode 100644 aplusb.cpp
How was this merge executed?
Before the merge, master points to 5ca15f0, while dev points to 5da093b, and these two states are not on the same line.
Git finds the nearest common ancestor of these two states (in the diagram, it is ae9dd37) and merges these three snapshots. The result of the merge of the three snapshots is treated as a new snapshot, and the current branch pointer moves to this snapshot.
The merge process itself is also a commit, but unlike regular commits, a merge commit has more than one parent commit; it is the result of merging multiple commit states.
After the merge is complete, the dev branch has fulfilled its purpose and can be deleted using the following command:
$ git branch -d dev # For unmerged branches, you can use the -D flag to force deletion
However, the merge process is not always smooth, and conflicts may occur in some cases. This issue will be addressed next.
Resolving Merge Conflicts
If different changes are made to the same part of the same file in two branches, Git cannot automatically merge the branches, resulting in a merge conflict.
Continuing from the previous example, suppose you started a new readme-refactor branch based on the merged master branch, intending to rewrite the README file. But due to some oversight, you made changes to the README file in both the readme-refactor and master branches.
Initially, the README file looks like this:
# This is a test repo.
This repo includes some c++ codes.
In the readme-refactor branch, the README file looks like this:
# Code Library
This repo includes some c++ codes.
In the master branch, the README file looks like this:
# This is a code library.
This repo includes some c++ codes.
Now, running the git merge readme-refactor command, Git indicates a merge conflict.
Run the git status command to see which files caused the conflict.
$ git status
On branch master
You have unmerged paths.
(fix conflicts and run "git commit")
Unmerged paths:
(use "git add <file>..." to mark resolution)
both modified: README.md
no changes added to commit (use "git add" and/or "git commit -a")
How to resolve the conflict? For each file that has a merge conflict, Git adds standard conflict resolution markers to the files. For example, in the README.md file in this example, it looks like this:
<<<<<< HEAD
# This is a code library.
======
# Code Library
>>>>>> readme-refactor
This repo includes some c++ codes.
The ====== line separates the content from the two branches, the part between <<<<<< HEAD and ====== is the content from the HEAD pointer (the master branch), and the part between ====== and >>>>>> readme-refactor is the content from the readme-refactor branch.
Edit the text to resolve the conflict by removing these conflict markers, save the file, add it to the staging area, and commit to resolve the merge conflict.
$ git add README.md # Add the conflicting file to the staging area
$ git commit
[master fe92c6b] Merge branch readme-refactor into master
Other Merge Methods
By default, Git uses the Merge method to merge two branches. When using this method to merge branch B into branch A, all commits from branch B will be included in branch A’s commit history.
In addition, Git provides two other ways to merge branches: Squash and Rebase.
Squash
Using the Squash method to merge branch B into branch A combines all changes from branch B into a single commit and commits it to branch A.
Add the --squash parameter in git merge to use the Squash method.
git merge <branch> --squash
Note that after executing the above command, Git only saves all changes from branch B in the staging area of branch A. You need to run git commit to complete the merge.
Using the Squash method simplifies the commit history but loses the detailed information of each commit (each commit’s author, changes, etc.), leaving only the combined information (each commit’s author will be listed as “Co-authored-by” in the commit message). However, if you use Squash and Merge on GitHub, the original information can be viewed in the Pull Request.
Rebase
Using the Rebase method to merge branch B into branch A adds each commit from branch B to branch A individually, rather than creating a merge commit to combine the contents of the two branches[^note2].
First, switch to branch B and then rebase it onto branch A:
git checkout B
git rebase A
Now switch back to branch A and run the git merge command to complete the merge of branch B into branch A.
git checkout A
git merge B
Using Rebase to complete the merge linearizes the commit history. When used correctly, Rebase can achieve better results than Merge in appropriate scenarios. However, it changes the commit history, increasing the likelihood of conflicts during the Rebase operation and subsequent merge operations. If not handled properly, it can make the commit history more chaotic. Therefore, if you are not fully familiar with Rebase operations, it is not recommended to use it.
Managing Remote Repositories
After making changes locally, you may need to push these changes to GitHub or other Git repository hosting platforms. Repositories hosted on these platforms fall under the category of remote repositories – you can fetch information from these repositories or push your changes to them. Collaborating with others often involves remote repositories, so it is essential to learn how to manage them.
Viewing Remote Repositories
Use the git remote command to view the list of remote repositories in the current repository.
If the current repository is cloned, there should be a remote repository called origin, with the link used
with the link used during cloning.
$ git remote
origin
To view detailed information about a specific remote repository, you can use:
$ git remote show origin
* remote origin
Fetch URL: [email protected]:example/example.git
Push URL: [email protected]:example/example.git
HEAD branch: master
Remote branches:
git tracked
master tracked
...
Configuring Remote Repositories
Use git remote add <name> <url> to add a remote repository named name with the URL url.
Use git remote rename <oldname> <newname> to rename a remote repository from oldname to newname.
Use git remote rm <name> to remove a remote repository named name.
Use git remote get-url <name> to view the URL of a remote repository named name.
Use git remote set-url <name> <newurl> to change the URL of a remote repository named name to newurl.
Fetching Changes from Remote Repositories
Other people may push changes to the remote repository. Use git fetch to fetch these changes to your local repository.
$ git fetch <remote-name> # Fetch changes from <remote-name>
Note that git fetch only fetches changes from the remote repository and does not merge these changes into your local repository. To merge these changes, use git pull. By default, git pull is equivalent to git fetch followed by git merge FETCH_HEAD.
$ git pull <remote-name> <branch> # Fetch changes from <remote-name> and merge them into HEAD
Pushing Changes to Remote Repositories
After making changes, use git push to push these changes to a remote repository.
$ git push <remote> <from>:<to> # Push changes from local <from> branch to <remote> <to> branch
You may need to enter your remote repository account username and password.
To successfully push your changes, you need to meet two conditions: you have write access to the repository (branch), and your local branch is newer than the corresponding remote branch (i.e., no one else has pushed to the remote branch while you were making changes). If the remote branch has new changes that your local branch does not, use git pull to merge these changes before pushing.
If you need to forcefully push your local changes to the remote repository, use the -f flag. This will overwrite the commit history of the remote repository with your local commit history, so use this command with caution. A better option is to use the --force-with-lease flag, which only overwrites the remote repository if it has not been updated. Note that “updated” refers to changes since the last fetch. If using VS Code’s Auto Fetch feature, be aware that this may make --force-with-lease as dangerous as -f.
Tracking Remote Branches
By setting a local branch to track a remote branch, you can easily view differences between the local and remote branches and simplify interactions with the remote branch.
Before tracking, fetch remote repository information with git fetch <remote-name>.
Then, execute git switch <remote-branch> to automatically create a new local branch named <remote-branch> and set it to track the corresponding remote branch.
Note that Git only automatically creates the branch and sets it to track the corresponding remote branch if the local branch does not exist and if only one remote branch matches the name.
Running git status will show the differences between the current branch and the remote branch.
Since the local branch is set to track the remote branch, pushing to the remote branch is simplified. Simply execute git push to push changes from the local branch to the tracked remote branch.
For existing local branches, set the corresponding remote tracking branch easily. Execute git branch -u <remote-name>/<remote-branch> in the current branch to set it to track <remote-name>/<remote-branch>.
Using SSH to Connect
Compared to HTTP(S), using SSH to connect to remote repositories is more convenient and secure.
Before using SSH to connect to a remote repository, add an SSH key locally. Then, upload the public key of the SSH key to the remote repository account.
For this guide, since it is mainly for example contributors, here is the GitHub Docs tutorial for reference.
After completing these steps, you can connect to the remote repository via SSH. Below is a command to clone the example repository using SSH:
$ git clone [email protected]:example/example.git
Pushing changes to the remote repository via SSH is similar to using HTTP(S), but using SSH avoids the need to authenticate with a username and password for the remote repository.
