From 52331ef4d00e122547d95240384ad2b612d0b609 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 22 Feb 2018 13:42:34 -0800 Subject: getting-started: Edits to the Git section. (From yocto-docs rev: d1512e2f9e17be58dcd8c64ce7911d6ee1ebc12c) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../getting-started-development-environment.xml | 44 +++++++++++++--------- 1 file changed, 26 insertions(+), 18 deletions(-) (limited to 'documentation') diff --git a/documentation/getting-started/getting-started-development-environment.xml b/documentation/getting-started/getting-started-development-environment.xml index 0c08859ea0..23021e1844 100644 --- a/documentation/getting-started/getting-started-development-environment.xml +++ b/documentation/getting-started/getting-started-development-environment.xml @@ -539,8 +539,8 @@ . - For examples beyond the limited few in this section on how - to use Git with the Yocto Project, see the + For information beyond the introductory nature in this + section, see the "Working With Yocto Project Source Files" section in the Yocto Project Development Tasks Manual. @@ -575,8 +575,8 @@ A Git repository represents all development efforts for a given project. For example, the Git repository poky contains - all changes and developments for Poky over the course of its - entire life. + all changes and developments for that repository over the course + of its entire life. That means that all changes that make up all releases are captured. The repository maintains a complete history of changes. @@ -653,15 +653,16 @@ of the upstream repository. In other words, creating and checking out a local branch based on the "&DISTRO_NAME_NO_CAP;" branch name is not the same as - cloning and checking out the "master" branch if the repository. + checking out the "master" branch in the repository. Keep reading to see how you create a local snapshot of a Yocto Project Release. - Git uses "tags" to mark specific changes in a repository. + Git uses "tags" to mark specific changes in a repository branch + structure. Typically, a tag is used to mark a special point such as the final - change before a project is released. + change (or commit) before a project is released. You can see the tags used with the poky Git repository by going to and @@ -671,7 +672,7 @@ - Some key tags for the poky are + Some key tags for the poky repository are jethro-14.0.3, morty-16.0.1, pyro-17.0.0, and @@ -704,15 +705,15 @@ tags available locally in your repository. Finally, the git checkout command creates and checks out a branch named "my-pyro-17.0.0" that is - based on the specific change upstream in the repository - associated with the "pyro-17.0.0" tag. + based on the upstream branch whose "HEAD" matches the + commit in the repository associated with the "pyro-17.0.0" tag. The files in your repository now exactly match that particular Yocto Project release as it is tagged in the upstream Git repository. It is important to understand that when you create and checkout a local working branch based on a tag, your environment matches a specific point in time and not the entire development - branch (i.e. the "tip" of the branch). + branch (i.e. from the "tip" of the branch backwards). @@ -740,7 +741,7 @@ The following list of Git commands briefly describes some basic Git operations as a way to get started. As with any set of commands, this list (in most cases) simply shows - the base command and omits the many arguments they support. + the base command and omits the many arguments it supports. See the Git documentation for complete descriptions and strategies on how to use these commands: @@ -781,12 +782,16 @@ git checkout branch-name: - Changes your working branch. + Changes your local working branch and in this form + assumes the local branch already exists. This command is analogous to "cd". - git checkout –b working-branch: + + git checkout –b working-branch upstream-branch: Creates and checks out a working branch on your local - machine that you can use to isolate your work. + machine. + The local branch tracks the upstream branch. + You can use your local branch to isolate your work. It is a good idea to use local branches when adding specific features or changes. Using isolated branches facilitates easy removal of @@ -806,15 +811,18 @@ branch-name. - git pull: + git pull --rebase: Retrieves information from an upstream Git repository and places it in your local Git repository. You use this command to make sure you are synchronized with the repository from which you are basing changes (.e.g. the "master" branch). + The "--rebase" option ensures that any local commits you + have in your branch are preserved at the top of your + local branch. - git push: + git push repo-name local-branch:upstream-branch: Sends all your committed local changes to the upstream Git repository that your local repository is tracking (e.g. a contribution repository). @@ -840,7 +848,7 @@ the isolated branch. - git cherry-pick: + git cherry-pick commits: Choose and apply specific commits from one branch into another branch. There are times when you might not be able to merge -- cgit v1.2.3-54-g00ecf