Teammates who are not familiar with Git have been a problem for a long time. In order to avoid teaching Git every time we work on a project, we have created this essential Git collaboration tutorial for teammates (reposting an old article, foggy).
Learning Git requires practice, and practice makes perfect.
If your teammate doesn't know Git, it's better not to team up
This article refers to Git Collaboration Tutorial | Crossroads of the Foreign Maze
Introduction#
What is a Git Repository? A project is a Git Repository. More specifically, the location of the project folder is the Git Repository. To turn a project folder into a Git Repository, you need to run the git init command to create a local Git repository (local means on your own computer). Of course, creating a Git code repository does not necessarily have to be local, you can also create a Git code repository through the Github website.
What is Git? Git is a version control system that manages file versions of Git Repositories. It saves your operations on the Git Repository. When needed, you can restore historical versions from the operation records.
What is Github? Github is a website for hosting Git Repositories. Users can upload their Git Repositories from their laptops to the Github website, and then download and edit them on desktop computers, or synchronize and collaborate with others (such as Dachu, foggy).
Installing Git can refer to the official Git website https://git-scm.com/ and various major blog websites, so I won't go into details.
It is recommended to use Git through the command line, but it may be a bit challenging for beginners. You can also use graphical interfaces.
There are many Git GUI (Graphical User Interface) tools, such as: Github Desktop, Sourcetree, GitKraken, and various IDEs with built-in Git GUIs.
I won't go into details about the installation. Please search on Bilibili and major blog websites.
Starting with Clone#
Use the git clone command to download the Repository (code repository) we need from Git Repository hosting websites such as Github.
As shown in the figure, this is the link address we need. We only need to use the git clone command, plus the address we copied, to fetch the repository we want.
git clone https://github.com/github/site-policy.git
The above code will fetch the site-policy repository from the official Github.
If you clone the repository using the command line method, please note that the repository will be downloaded to the current path of the command line. You can use the cd command to change the path. For more details, please refer to major blog platforms.
If you have the ability, you can configure SSH Key for Github, so that you can clone code repositories using the SSH protocol. Again, I won't go into details here.
When we finish cloning the code repository, it means that we also have a local repository on our own computer, which is exactly the same as the remote repository on the Github website.
We call the code repository on our own computer the local repository, and the code repository on Github or other hosting websites the remote repository.
❗❗When you open the local repository on your computer, you may find a hidden folder named .git, and you need to pay special attention to it. This .git folder contains all the modification records and remote connection information of the repository. ❗❗If you delete the .git folder, the current project will no longer be a repository and will be no different from an ordinary folder.
Git Code Changes and Uploads#
As mentioned earlier, the project folder can be considered as a Git Repository.
For code files, it is inevitable that we will delete some errors and add some features, which involves creating, deleting, and modifying files.
Does pressing Ctrl+S update the code repository? Not exactly.
The Ctrl+S shortcut saves the file, but does not update the Git records. In other words, from our perspective, the code has indeed been modified, but from Git's perspective, the code has not changed.
The same applies to file creation and deletion.
So, how can we make Git aware of the file changes?
You need to use the git add command.
git add *
Here, * is a wildcard that applies to all files.
For other usages, you can refer to git add command | Runoob Tutorial or related blog articles on major websites.
Although Git is aware of your file modifications (the files are in the staging area), it has not generated operation records (the modifications have not entered the local repository).
Since this is the case, how do we update the Git repository?
You need to use the git commit command to commit the changes to the local repository. At this time, "operation records" will be generated in the git log.
git commit -m "my first commit"
Here, -m is a parameter passed to the commit operation, which serves as a summary of this commit.
Commit message template
Refer to conventional commits or Commit message and Change log writing guide - Ruanyifeng's Blog for simplicity and clarity.
For other usages of the git commit command, you can refer to git commit command | Runoob Tutorial and other tutorial materials.
So far, we have successfully updated the local repository on our own computer.
But along with it comes a problem—the remote repository on the Github website, which has not been touched by anyone, and now the two repositories are inconsistent.
We upload the updated version (the modified local repository) to Github to update the remote repository.
This process uses the git push command.
git push origin main
After executing the above code, the local main branch will be uploaded and overwritten to the remote main branch.
Refer to git push command | Runoob Tutorial for more syntax details. You can also refer to other tutorial websites.
Git Code Synchronization and Download#
When the remote code repository on Github or other hosting websites is newer than the local code repository on your computer, we need to download the code.
In this case, you can use the git pull command.
git pull origin main
At this time, the remote main branch of the code repository will be pulled down and then update the local main branch.
For more information, you can refer to git pull command | Runoob Tutorial and other resources.
Code Conflicts and Resolution The following is an example of a code conflict taken from the internet.
<<<<<<<<<<<
A
===========
B
>>>>>>>>>>>
These markers are called conflict markers. As shown above, A and B conflict with each other.
IDEs usually automatically recognize conflict markers, highlight the conflicting code (displayed in green and blue in the figure), and provide a shortcut menu for conflict resolution, including options such as Accept Current Change, Accept Incoming Change, Accept Both Change, and Compare Changes. Click on the corresponding option to choose between the two code segments.
Sometimes, conflict markers may not be recognized correctly, so you need to manually delete duplicate code and conflict markers, otherwise the merge will fail.
In fact, the same situation may occur when pushing code. The resolution method is similar.
Branch Management#
Use the git branch command and git checkout command to create branches and switch branches. I won't go into details about the usage, please refer to git branch command | Runoob Tutorial and other related materials.
Branch naming and functionality in Git:
- master/main (main branch, always a stable version, should not be developed directly)
- develop (development main branch, all new features are created on this branch, this branch only does merge operations, should not be developed directly)
- feature-xxx (feature development branch, created on develop branch for developing specific features, merge to develop branch after feature testing is successful)
- feature-xxx-fix (feature bug fix branch, created on develop branch for fixing bugs found after merging feature branch, then merge back to develop branch)
- hotfix-xxx (emergency bug fix branch, created on master branch, merge to master after fixing is completed)
- bugfix/* branches (created temporarily from develop)
- release/* branches (created temporarily from develop)
The relationship between branches can be seen in the following diagram.
As mentioned above, in projects with multiple collaborators, progress is often made in parallel with multiple branches. Directly pushing to the main/master branch and develop branch is not allowed.
Use Pull Request (PR) to merge code. The PR method can avoid unexpected results caused by direct push, support code review, and introduce automated tools for assistance, etc.
You can refer to Why you shouldn't push directly to master | Weitang Li's blog for more details.
How to create a PR can be seen in the figure below, follow the instructions on the page to operate.
Essential Development Process#
Here are a few important points that must be emphasized.
Always perform a pull operation before development#
Always pull before each development❗ to resolve potential conflicts and update the code. It also avoids duplicate work.
Do not develop using the main (master) branch and develop (dev) branch#
We prohibit pushing directly to the main branch and develop branch. It is best to develop on a separate feature branch.
The naming of the feature-xxx branch can be based on the specific feature being developed. Then use PR to merge the code.
PR direction: Submit from the feat branch to the dev branch, and then submit from the dev branch to the main branch, do not skip levels.
Violating this step will result in branch chaos, and the consequences will be extremely difficult.
Clearly describe the commit message when submitting code and PR#
Tell your teammates what you have done❗ to save everyone's time. See the previous text for details.
Branch merging requires review#
Usually, PRs are not approved immediately and may require code review by other members of the team before they can be merged. Pay attention to the comments section of the PR page to receive feedback and modification suggestions in a timely manner.
If you are unsure, ask in the group#
For example, if a code conflict occurs, it is not necessarily someone else's code that is wrong;
For example, there may be unfamiliar problems...
Searching for solutions is one aspect, but be sure to let other team members know, don't work in isolation 😅
Good Luck#
Good luck