From fcb53beee46fd5b3b600232bef4d6bf7e76ef49e Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 15 Jun 2017 11:41:25 -0700 Subject: [PATCH] documentation: Moved "Git" section to the ref-manual Fixes [YOCTO #11630] The "Git" section in the dev-manual is really about concepts. There are a couple of examples that might or not might be allowed to ultimately stay. I have moved the section to the ref-manual. If those examples get replicated in the new dev-manual, I will update the "Git" section further. For now, however, these remain in this moved section. (From yocto-docs rev: 2e4b87fdab29c13ce0d2314e50c93e37404b6f7e) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/bsp-guide/bsp.xml | 2 +- .../dev-manual/dev-manual-newbie.xml | 269 +------------ documentation/dev-manual/dev-manual-start.xml | 6 +- .../kernel-dev/kernel-dev-concepts-appx.xml | 6 +- .../kernel-dev/kernel-dev-examples.xml | 4 +- documentation/ref-manual/introduction.xml | 4 +- documentation/ref-manual/migration.xml | 2 +- .../ref-development-environment.xml | 356 +++++++++++++++++- documentation/ref-manual/usingpoky.xml | 2 +- documentation/sdk-manual/sdk-extensible.xml | 2 +- .../yocto-project-qs/yocto-project-qs.xml | 2 +- 11 files changed, 373 insertions(+), 282 deletions(-) diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index 7dc7ad37d9..f9fcf10105 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -1144,7 +1144,7 @@ Designed to have a command interface somewhat like - Git, each + Git, each tool is structured as a set of sub-commands under a top-level command. The top-level command (yocto-bsp diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index c2147b39e7..97e2590763 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -167,7 +167,7 @@ with the OpenEmbedded build system is advisable. Of the SCMs BitBake supports, the Yocto Project team strongly recommends using - Git. + Git. Git is a distributed system that is easy to backup, allows you to work remotely, and then connects back to the infrastructure. @@ -306,7 +306,7 @@ This section summarizes the key recommendations described in the previous sections: - Use Git + Use Git as the source control system. Maintain your Metadata in layers that make sense for your situation. @@ -354,269 +354,6 @@ -
- Git - - - The Yocto Project makes extensive use of Git, - which is a free, open source distributed version control system. - Git supports distributed development, non-linear development, and can handle large projects. - It is best that you have some fundamental understanding of how Git tracks projects and - how to work with Git if you are going to use the Yocto Project for development. - This section provides a quick overview of how Git works and provides you with a summary - of some essential Git commands. - - - - For more information on Git, see - . - If you need to download Git, go to . - - -
- Repositories, Tags, and Branches - - - As mentioned earlier in the section - "Yocto Project Source Repositories", - the Yocto Project maintains source repositories at - . - If you look at this web-interface of the repositories, each item is a separate - Git repository. - - - - Git repositories use branching techniques that track content change (not files) - within a project (e.g. a new feature or updated documentation). - Creating a tree-like structure based on project divergence allows for excellent historical - information over the life of a project. - This methodology also allows for an environment from which you can do lots of - local experimentation on projects as you develop changes or new features. - - - - 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. - That means that all changes that make up all releases are captured. - The repository maintains a complete history of changes. - - - - You can create a local copy of any repository by "cloning" it with the Git - clone command. - When you clone a Git repository, you end up with an identical copy of the - repository on your development system. - Once you have a local copy of a repository, you can take steps to develop locally. - For examples on how to clone Git repositories, see the - "Getting Set Up" section. - - - - It is important to understand that Git tracks content change and - not files. - Git uses "branches" to organize different development efforts. - For example, the poky repository has - several branches that include the current - &DISTRO_NAME_NO_CAP; branch, the - master branch, and many branches for past - Yocto Project releases. - You can see all the branches by going to - and - clicking on the - [...] - link beneath the "Branch" heading. - - - - Each of these branches represents a specific area of development. - The master branch represents the current or most recent - development. - All other branches represent offshoots of the master - branch. - - - - When you create a local copy of a Git repository, the copy has the same set - of branches as the original. - This means you can use Git to create a local working area (also called a branch) - that tracks a specific development branch from the source Git repository. - in other words, you can define your local Git environment to work on any development - branch in the repository. - To help illustrate, here is a set of commands that creates a local copy of the - poky Git repository and then creates and checks out a local - Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development: - - $ cd ~ - $ git clone git://git.yoctoproject.org/poky - $ cd poky - $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; - - In this example, the name of the top-level directory of your local - Source Directory - is "poky" and the name of that local working area (local branch) - you just created and checked out is "&DISTRO_NAME_NO_CAP;". - The files in your local repository now reflect the same files that - are in the "&DISTRO_NAME_NO_CAP;" development branch of the - Yocto Project's "poky" upstream repository. - It is important to understand that when you create and checkout a - local working branch based on a branch name, - your local environment matches the "tip" of that development branch - at the time you created your local branch, which could be - different from the files at the time of a similarly named release. - 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. - 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. - Typically, a tag is used to mark a special point such as the final - change before a project is released. - You can see the tags used with the poky Git - repository by going to - and - clicking on the - [...] - link beneath the "Tag" heading. - - - - Some key tags are - dizzy-12.0.0, - fido-13.0.0, - jethro-14.0.0, and - &DISTRO_NAME_NO_CAP;-&POKYVERSION;. - These tags represent Yocto Project releases. - - - - When you create a local copy of the Git repository, you also have access to all the - tags. - Similar to branches, you can create and checkout a local working Git branch based - on a tag name. - When you do this, you get a snapshot of the Git repository that reflects - the state of the files when the change was made associated with that tag. - The most common use is to checkout a working branch that matches a specific - Yocto Project release. - Here is an example: - - $ cd ~ - $ git clone git://git.yoctoproject.org/poky - $ cd poky - $ git checkout -b my-&DISTRO_NAME_NO_CAP;-&POKYVERSION; &DISTRO_NAME_NO_CAP;-&POKYVERSION; - - In this example, the name of the top-level directory of your local Yocto Project - Files Git repository is poky. - And, the name of the local branch you have created and checked out is - my-&DISTRO_NAME_NO_CAP;-&POKYVERSION;. - The files in your repository now exactly match the Yocto Project &DISTRO; - Release tag (&DISTRO_NAME_NO_CAP;-&POKYVERSION;). - 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. - -
- -
- Basic Commands - - - Git has an extensive set of commands that lets you manage changes and perform - collaboration over the life of a project. - Conveniently though, you can manage with a small set of basic operations and workflows - once you understand the basic philosophy behind Git. - You do not have to be an expert in Git to be functional. - A good place to look for instruction on a minimal set of Git commands is - here. - If you need to download Git, you can do so - here, although - any reasonably current Linux distribution should already have an - installable package for Git. - - - - If you do not know much about Git, you should educate - yourself by visiting the links previously mentioned. - - - - The following list 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. - See the Git documentation for complete descriptions and strategies on how to use these commands: - - git init: Initializes an empty Git repository. - You cannot use Git commands unless you have a .git repository. - git clone: - Creates a local clone of a Git repository. - During collaboration, this command allows you to create a - local Git repository that is on equal footing with a fellow - developer’s Git repository. - - git add: Stages updated file contents - to the index that - Git uses to track changes. - You must stage all files that have changed before you can commit them. - git commit: Creates a "commit" that documents - the changes you made. - Commits are used for historical purposes, for determining if a maintainer of a project - will allow the change, and for ultimately pushing the change from your local Git repository - into the project’s upstream (or master) repository. - git status: Reports any modified files that - possibly need to be staged and committed. - git checkout branch-name: Changes - your working branch. - This command is analogous to "cd". - git checkout –b working-branch: Creates - a working branch on your local machine where you can isolate work. - It is a good idea to use local branches when adding specific features or changes. - This way if you do not like what you have done you can easily get rid of the work. - git branch: Reports - existing local branches and - tells you the branch in which you are currently working. - git branch -D branch-name: - Deletes an existing local branch. - You need to be in a local branch other than the one you are deleting - in order to delete branch-name. - git pull: 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). - git push: - Sends all your committed local changes to an upstream Git - repository (e.g. a contribution repository). - The maintainer of the project draws from these repositories - when adding changes to the project’s master repository or - other development branch. - - git merge: Combines or adds changes from one - local branch of your repository with another branch. - When you create a local Git repository, the default branch is named "master". - A typical workflow is to create a temporary branch for isolated work, make and commit your - changes, switch to your local master branch, merge the changes from the temporary branch into the - local master branch, and then delete the temporary branch. - git cherry-pick: Choose and apply specific - commits from one branch into another branch. - There are times when you might not be able to merge all the changes in one branch with - another but need to pick out certain ones. - gitk: Provides a GUI view of the branches - and changes in your local Git repository. - This command is a good way to graphically see where things have diverged in your - local repository. - git log: Reports a history of your changes to the - repository. - git diff: Displays line-by-line differences - between your local working files and the same files in the upstream Git repository that your - branch currently tracks. - - -
-
-
Submitting a Defect Against the Yocto Project @@ -862,7 +599,7 @@ Search by File: - Using Git, you can enter the + Using Git, you can enter the following command to bring up a short list of all commits against a specific file: diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml index 4dbcc7e34a..df622f93b9 100644 --- a/documentation/dev-manual/dev-manual-start.xml +++ b/documentation/dev-manual/dev-manual-start.xml @@ -87,7 +87,7 @@ The documentation refers to this set of locally installed files as the Source Directory. You create your Source Directory by using - Git to clone a local copy + Git to clone a local copy of the upstream poky repository, or by downloading and unpacking a tarball of an official Yocto Project release. @@ -110,7 +110,7 @@ The command creates the local repository in a directory named poky. For information on Git used within the Yocto Project, see - the "Git" section. + the "Git" section. $ git clone git://git.yoctoproject.org/poky Cloning into 'poky'... @@ -241,7 +241,7 @@ . Using - Git to create a local clone of the + Git to create a local clone of the upstream repository can be helpful if you are working with BSPs. Typically, you set up the meta-intel diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml index ac91749cd6..8ecd04d32c 100644 --- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml +++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml @@ -107,7 +107,7 @@ The features are tagged and organized by way of a branching strategy implemented by the source code manager (SCM) Git. For information on Git as applied to the Yocto Project, see the - "Git" section in the + "Git" section in the Yocto Project Development Manual. @@ -235,8 +235,8 @@ You can find documentation on Git at . You can also get an introduction to Git as it applies to the Yocto Project in the - "Git" - section in the Yocto Project Development Manual. + "Git" + section in the Yocto Project Reference Manual. These referenced sections overview Git and describe a minimal set of commands that allows you to be functional using Git. diff --git a/documentation/kernel-dev/kernel-dev-examples.xml b/documentation/kernel-dev/kernel-dev-examples.xml index 9d9aef6d06..3ea217f3c4 100644 --- a/documentation/kernel-dev/kernel-dev-examples.xml +++ b/documentation/kernel-dev/kernel-dev-examples.xml @@ -241,8 +241,8 @@ You can find Git documentation at . You can find a simple overview of using Git with the Yocto Project in the - "Git" - section of the Yocto Project Development Manual. + "Git" + section of the Yocto Project Reference Manual.
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml index 1fc01fe38a..9e6c751987 100644 --- a/documentation/ref-manual/introduction.xml +++ b/documentation/ref-manual/introduction.xml @@ -1035,8 +1035,8 @@ For more information on concepts related to Git repositories, branches, and tags, see the - "Repositories, Tags, and Branches" - section in the Yocto Project Development Manual. + "Repositories, Tags, and Branches" + section. Task: A unit of execution for BitBake (e.g. diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml index a3dc1ee1f6..b90a7d1213 100644 --- a/documentation/ref-manual/migration.xml +++ b/documentation/ref-manual/migration.xml @@ -1748,7 +1748,7 @@ The minimum - Git version required + Git version required on the build host is now 1.7.8 because the --list option is now required by BitBake's Git fetcher. diff --git a/documentation/ref-manual/ref-development-environment.xml b/documentation/ref-manual/ref-development-environment.xml index 08e790b7a2..234800df69 100644 --- a/documentation/ref-manual/ref-development-environment.xml +++ b/documentation/ref-manual/ref-development-environment.xml @@ -256,6 +256,360 @@
+
+ Git + + + The Yocto Project makes extensive use of Git, which is a + free, open source distributed version control system. + Git supports distributed development, non-linear development, + and can handle large projects. + It is best that you have some fundamental understanding + of how Git tracks projects and how to work with Git if + you are going to use the Yocto Project for development. + This section provides a quick overview of how Git works and + provides you with a summary of some essential Git commands. + + + + For more information on Git, see + . + If you need to download Git, it is recommended that you add Git + to your system through your distribution's "software store" + (e.g. for Ubuntu, use the Ubuntu Software feature). + For the Git download page, see + . + + +
+ Repositories, Tags, and Branches + + + As mentioned briefly in the previous section and also in the + "Workflows" section, + the Yocto Project maintains source repositories at + . + If you look at this web-interface of the repositories, each item + is a separate Git repository. + + + + Git repositories use branching techniques that track content + change (not files) within a project (e.g. a new feature or updated + documentation). + Creating a tree-like structure based on project divergence allows + for excellent historical information over the life of a project. + This methodology also allows for an environment from which you can + do lots of local experimentation on projects as you develop + changes or new features. + + + + 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. + That means that all changes that make up all releases are captured. + The repository maintains a complete history of changes. + + + + You can create a local copy of any repository by "cloning" it + with the git clone command. + When you clone a Git repository, you end up with an identical + copy of the repository on your development system. + Once you have a local copy of a repository, you can take steps to + develop locally. + For examples on how to clone Git repositories, see the + "Getting Set Up" + section in the Yocto Project Development Manual. + + + + It is important to understand that Git tracks content change and + not files. + Git uses "branches" to organize different development efforts. + For example, the poky repository has + several branches that include the current "&DISTRO_NAME_NO_CAP;" + branch, the "master" branch, and many branches for past + Yocto Project releases. + You can see all the branches by going to + and + clicking on the + [...] + link beneath the "Branch" heading. + + + + Each of these branches represents a specific area of development. + The "master" branch represents the current or most recent + development. + All other branches represent offshoots of the "master" branch. + + + + When you create a local copy of a Git repository, the copy has + the same set of branches as the original. + This means you can use Git to create a local working area + (also called a branch) that tracks a specific development branch + from the upstream source Git repository. + in other words, you can define your local Git environment to + work on any development branch in the repository. + To help illustrate, consider the following example Git commands: + + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; + + In the previous example after moving to the home directory, the + git clone command creates a + local copy of the upstream poky Git repository. + By default, Git checks out the "master" branch for your work. + After changing the working directory to the new local repository + (i.e. poky), the + git checkout command creates + and checks out a local branch named "&DISTRO_NAME_NO_CAP;", which + tracks the upstream "origin/&DISTRO_NAME_NO_CAP;" branch. + Changes you make while in this branch would ultimately affect + the upstream "&DISTRO_NAME_NO_CAP;" branch of the + poky repository. + + + + It is important to understand that when you create and checkout a + local working branch based on a branch name, + your local environment matches the "tip" of that particular + development branch at the time you created your local branch, + which could be different from the files in the "master" branch + 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. + 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. + Typically, a tag is used to mark a special point such as the final + change before a project is released. + You can see the tags used with the poky Git + repository by going to + and + clicking on the + [...] + link beneath the "Tag" heading. + + + + Some key tags for the poky are + jethro-14.0.3, + morty-16.0.1, + pyro-17.0.0, and + &DISTRO_NAME_NO_CAP;-&POKYVERSION;. + These tags represent Yocto Project releases. + + + + When you create a local copy of the Git repository, you also + have access to all the tags in the upstream repository. + Similar to branches, you can create and checkout a local working + Git branch based on a tag name. + When you do this, you get a snapshot of the Git repository that + reflects the state of the files when the change was made associated + with that tag. + The most common use is to checkout a working branch that matches + a specific Yocto Project release. + Here is an example: + + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git fetch --all --tags --prune + $ git checkout tags/pyro-17.0.0 -b my-pyro-17.0.0 + + In this example, the name of the top-level directory of your + local Yocto Project repository is poky. + After moving to the poky directory, the + git fetch command makes all the upstream + 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. + 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). + +
+ +
+ Basic Commands + + + Git has an extensive set of commands that lets you manage changes + and perform collaboration over the life of a project. + Conveniently though, you can manage with a small set of basic + operations and workflows once you understand the basic + philosophy behind Git. + You do not have to be an expert in Git to be functional. + A good place to look for instruction on a minimal set of Git + commands is + here. + + + + If you do not know much about Git, you should educate + yourself by visiting the links previously mentioned. + + + + 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. + See the Git documentation for complete descriptions and strategies + on how to use these commands: + + + git init: + Initializes an empty Git repository. + You cannot use Git commands unless you have a + .git repository. + + + git clone: + Creates a local clone of a Git repository that is on + equal footing with a fellow developer’s Git repository + or an upstream repository. + + + git add: + Locally stages updated file contents to the index that + Git uses to track changes. + You must stage all files that have changed before you + can commit them. + + + git commit: + Creates a local "commit" that documents the changes you + made. + Only changes that have been staged can be committed. + Commits are used for historical purposes, for determining + if a maintainer of a project will allow the change, + and for ultimately pushing the change from your local + Git repository into the project’s upstream repository. + + + git status: + Reports any modified files that possibly need to be + staged and gives you a status of where you stand regarding + local commits as compared to the upstream repository. + + + git checkout branch-name: + Changes your working branch. + This command is analogous to "cd". + + git checkout –b working-branch: + Creates and checks out a working branch on your local + machine that you can use 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 + changes if they do not work out. + + git branch: + Displays the existing local branches associated with your + local repository. + The branch that you have currently checked out is noted + with an asterisk character. + + + git branch -D branch-name: + Deletes an existing local branch. + You need to be in a local branch other than the one you + are deleting in order to delete + branch-name. + + + git pull: + 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). + + + git push: + Sends all your committed local changes to the upstream Git + repository that your local repository is tracking + (e.g. a contribution repository). + The maintainer of the project draws from these repositories + to merge changes (commits) into the appropriate branch + of project's upstream repository. + + + git merge: + Combines or adds changes from one + local branch of your repository with another branch. + When you create a local Git repository, the default branch + is named "master". + A typical workflow is to create a temporary branch that is + based off "master" that you would use for isolated work. + You would make your changes in that isolated branch, + stage and commit them locally, switch to the "master" + branch, and then use the git merge + command to apply the changes from your isolated branch + into the currently checked out branch (e.g. "master"). + After the merge is complete and if you are done with + working in that isolated branch, you can safely delete + the isolated branch. + + + git cherry-pick: + Choose and apply specific commits from one branch + into another branch. + There are times when you might not be able to merge + all the changes in one branch with + another but need to pick out certain ones. + + + gitk: + Provides a GUI view of the branches and changes in your + local Git repository. + This command is a good way to graphically see where things + have diverged in your local repository. + + You need to install the gitk + package on your development system to use this + command. + + + + git log: + Reports a history of your commits to the repository. + This report lists all commits regardless of whether you + have pushed them upstream or not. + + + git diff: + Displays line-by-line differences between a local + working file and the same file as understood by Git. + This command is useful to see what you have changed + in any given file. + + + +
+
+
Yocto Project Source Repositories @@ -290,7 +644,7 @@ Source Directory and the files for supported BSPs (e.g., meta-intel) is to use - Git to create a local copy of + Git to create a local copy of the upstream repositories. diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml index 9fb74172b5..c81818840a 100644 --- a/documentation/ref-manual/usingpoky.xml +++ b/documentation/ref-manual/usingpoky.xml @@ -1110,7 +1110,7 @@ Enabling build history as previously described causes the build process to collect build output information and commit it to a local - Git repository. + Git repository. Enabling build history increases your build times slightly, particularly for images, and increases the amount of disk diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml index 44cb94722f..415cf679ee 100644 --- a/documentation/sdk-manual/sdk-extensible.xml +++ b/documentation/sdk-manual/sdk-extensible.xml @@ -240,7 +240,7 @@ The devtool command line is organized similarly to - Git in that it has a + Git in that it has a number of sub-commands for each function. You can run devtool --help to see all the commands. diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml index 527fcd86cc..b069b3d459 100644 --- a/documentation/yocto-project-qs/yocto-project-qs.xml +++ b/documentation/yocto-project-qs/yocto-project-qs.xml @@ -378,7 +378,7 @@ Yocto Project is getting a Yocto Project release. It is recommended that you get the latest Yocto Project release by setting up (cloning in - Git terms) a + Git terms) a local copy of the poky Git repository on your build host and then checking out the latest release. Doing so allows you to easily update to newer Yocto Project