GitHub 基本概念

GitHub是一個面向開源及私有軟件項(xiàng)目的托管平臺狈涮，可作為開源代碼庫以及版本控制系颤介〉基本概念有：

Issue:This is a work item (RTC-lingo), or a ticket (support lingo). An issue is required for doc work or major decisions.

Branch: Basically a copy of the doc where you apply the changes. Branches named master or branch_prod are set as the branches that are published at GA or for a refresh. (See the properties files to understand how branches are published. These are the final copies, and your branch off of those branches is your workspace. You never update the main production branches without a pull request.

For example, if I want to work on 1.2, I need to check out 1.2_prod, run git pull to get the latest changes that were committed by the team, then checkout my own branch from prod. If you do not run git pull before you check out your branch, you don’t have the most recent copy of the branch.

Pull request: Since you opened your own branch, <my-branch>, against the production branch, you must create a pull request to get your changes into the main branch <_stage>. (Really, think of it as a PUSH request.)

Commit: Used as a verb, or noun. When you check in your changes, you are “committing” to your branch. A “commit” is your change. Think: Checking in code.

Repository: Everything–the code, the branches, the history…all takes place in the repo. The repo is not the branch, but the repo contains all the branches.

Clone: When you are ready to start, you first have to clone the repo. You should only do this once at the beginning, then you always have the repo, you just check out the branches you need. Cloning pulls the copy of the staging branch to your machine.

GitHub 基本流程

1. Clone your repo files to your local computer.

Context: Here you are downloading the repository files to your local computer.??

Steps:

a. Open your GitHub repository in GitHub webpage and click Clone or download. ?

b. A Launch Application window might appear asking you if you want to open in github desktop.exe, select Remember my choice and click Open link. ?

c. Click Open in Desktop. ?

d. In GitHub Desktop, observe the current repository and current branch.

2. Create a branch for your work in GitHub Desktop.

Context: Here you are taking a copy of the current repo – you will work on this copy and then merge it back into the current repo. You are also publishing your copy of the repo so that it is available for others to work on.?

Steps:

a. In GitHub Desktop, click the arrow next to Current branch.?

b. Click New branch. ?

c. Enter a name for the branch – it is best practice to give it a name that’s not easily confused with the default branch in your repository, for example, myname_active_branch.?

d. Click on Create new branch. You should see that it is creating a branch based on the default branch. ?

e. Click Create branch.?

f . Click Publish Branch

Result: You should now be able to see your branch in GitHub Desktop and GitHub webpage.

3. Edit a file.?

Context: Here you edit your file in Visual Studio, commit to your local branch and then push to github.?

a. In Github Desktop, click Open in Visual Studio Code.?

b. Navigate to the file/s you want to edit in Visual Studio Code and edit the file/s directly.?

c.? Click Save. ?

d. Once you click Save you will see that in Github Desktop, the Commit to your_branch button becomes available. Click Commit to your_branch. ?

e. Click Push origin.?

Result: You should now be able to go to the repo, select your branch and see that your edit is completed in your branch.

4. Create a pull request and merge your content.

Context: Next you want to create a pull request to get your content reviewed. There are 2 different ways of doing this.?

a. In Github desktop, with your current branch where you made your changes selected, click Create Pull Request.

b. In the Open a pull request, ensure:?

- the pull request is going from your branch to the default branch.

- the file/s you edited are listed.

- reviewers are suggested, especially those topics owned by many people. For example, toc or conref files.

5. Although GitHub Desktop is easier to use, sometimes it's still needed to use Git Bash (CLI).

a. You need to use git pull origin <default_branch_name> to pull latest changes of the default repo to your local working branch.? <default_branch_name> here means the branch that is used to publish to KC.

In this way, you can ensure you work on the latest repo and the changes of other colleagues are not overwritten.

Best practice is: Before your start your document work everyday, run git pull origin <default_branch_name> first. This can help to decrease the conflict when merging to the default branch.

b. Sometimes you may have conflicts between your custom branch and the default branch and you don't know how to handle.

An easy way is: first save the changed file to another file. Then remove the custom branch by the following commands. Create a new custom branch from GitHub Desktop, and run git pull origin <default_branch_name> to get a newest version of the default branch. At last, re-edit the file based on the changed file contents.

delete the local branch:git branch -d <your_custom_branch-name>

delete the remote branch in githubgit push origin --delete <your_custom_branch-name>

c. Other commands:

Running the command to enter your branch.?

git checkout <your own branch>

Creating a branch:?

git checkout -b <branch name>

Publishing a branch to the remote Github repository:?

git push -u origin <branch name>

Seeing a list of branches:?

git branch -l

Switching to a different branch:?

git checkout <branch name>

Creating a branch:?

git checkout -b <branch name>

Publishing a branch to the remote Github repository:?

git push -u origin <branch name>

Seeing a list of branches:?

git branch -l

Switching to a different branch:?

git checkout <branch name>

Deleting a branch:?

git branch <branch name> -d

Cloning the docs repo:

?git clone git@<repo_name>

Committing changes:

git add .

git commit -m "Issue 1 #xxxx - I changed lots of stuff"

git cherry-pick [commit_ID]. See https://stackoverflow.com/questions/9339429/what-does-cherry-picking-a-commit-with-git-mean

Pushing content:

?git push

?git push --set-upstream origin [branch]