From 74c120f2737d09b30d75e828b7ab0eeb8460a68e Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 14 Jul 2011 07:47:26 -0700 Subject: documentation/kernel-manual/kernel-how-to.xml: changed git to Git as needed (From yocto-docs rev: 65a839ea3d8decd1dd3e95bfeeeb3f95cfa77ef4) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/kernel-manual/kernel-how-to.xml | 144 +++++++++++++------------- 1 file changed, 72 insertions(+), 72 deletions(-) (limited to 'documentation/kernel-manual') diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml index 0e344c44a9..0f7e03f23f 100644 --- a/documentation/kernel-manual/kernel-how-to.xml +++ b/documentation/kernel-manual/kernel-how-to.xml @@ -41,16 +41,16 @@ You can find the files used to describe all the valid features and BSPs in the Yocto Project - kernel in any clone of the kernel git tree. + kernel in any clone of the kernel Git tree. The directory meta/cfg/kernel-cache/ is a snapshot of all the kernel configuration and feature descriptions (.scc) used to build the kernel repository. You should realize, however, that browsing the snapshot of feature descriptions and patches is not an effective way to determine what is in a particular kernel branch. - Instead, you should use git directly to discover the changes + Instead, you should use Git directly to discover the changes in a branch. - Using git is an efficient and flexible way to inspect changes to the kernel. - For examples showing how to use git to inspect kernel commits, see the following sections + Using Git is an efficient and flexible way to inspect changes to the kernel. + For examples showing how to use Git to inspect kernel commits, see the following sections in this chapter. @@ -91,13 +91,13 @@ The script is executed, and a meta-series is produced. The meta-series is a description of all the branches, tags, patches and configurations that - need to be applied to the base git repository to completely create the + need to be applied to the base Git repository to completely create the BSP source (build) branch. The base repository is cloned, and the actions listed in the meta-series are applied to the tree. - The git repository is left with the desired branch checked out and any + The Git repository is left with the desired branch checked out and any required branching, patching and tagging has been performed. @@ -137,7 +137,7 @@ A summary of end user tree construction activities follow: compile and link a full top-down kernel description from feature descriptions execute the complete description to generate a meta-series - interpret the meta-series to create a customized git repository for the + interpret the meta-series to create a customized Git repository for the board migrate configuration fragments and configure the kernel checkout the BSP branch and build @@ -153,7 +153,7 @@ A summary of end user tree construction activities follow: - There must be a kernel git repository indicated in the SRC_URI. + There must be a kernel Git repository indicated in the SRC_URI. There must be a BSP build branch - <bsp name>-<kernel type> in 0.9 or <kernel type>/<bsp name> in 1.0. @@ -186,7 +186,7 @@ A summary of end user tree construction activities follow: The other thing that you will first see once you configure a kernel is that - it will generate a build tree that is separate from your git source tree. + it will generate a build tree that is separate from your Git source tree. This build tree has the name using the following form: linux-<BSPname>-<kerntype>-build @@ -203,7 +203,7 @@ A summary of end user tree construction activities follow: The files include the final .config, all the .o files, the .a files, and so forth. Since each BSP has its own separate build directory in its own separate branch - of the git tree you can easily switch between different BSP builds. + of the Git tree you can easily switch between different BSP builds. @@ -222,7 +222,7 @@ to be used or not. The 2.0 release already made use of some stateful construction of series files, but since the delivery mechanism was unchanged (tar + patches + series files), most people were not aware of anything really different. The 3.0 release continues with this stateful construction of -series files, but since the delivery mechanism is changed (git + branches) it +series files, but since the delivery mechanism is changed (Git + branches) it now is more apparent to people. @@ -231,7 +231,7 @@ compiler". Its role is to combine feature descriptions into a format that can be used to generate a meta-series. A meta series contains all the required information to construct a complete set of branches that are required to build a desired board and feature set. The meta series is interpreted by the -kgit tools to create a git repository that could be built. +kgit tools to create a Git repository that could be built. To illustrate how scc works, a feature description must first be understood. @@ -248,7 +248,7 @@ Each feature description can use any of the following valid scc commands: shell constructs: bash conditionals and other utilities can be used in a feature description. During compilation, the working directory is the feature description itself, so any command that is "raw shell" and not from the - list of supported commands, can not directly modify a git repository. + list of supported commands, can not directly modify a Git repository. patch <relative path>/<patch name>: outputs a patch to be included in a feature's patch set. Only the name of the patch is supplied, the path is calculated from the currently set @@ -299,9 +299,9 @@ Each feature description can use any of the following valid scc commands: include is processed, so is normally only used by a new top level feature to modify the order of features in something it is including. - git <command>: Issues any git command during tree construction. Note: this command is + git <command>: Issues any Git command during tree construction. Note: this command is not validated/sanitized so care must be taken to not damage the - tree. This can be used to script branching, tagging, pulls or other git + tree. This can be used to script branching, tagging, pulls or other Git operations. dir <directory>: changes the working directory for "patch" directives. This can be used to @@ -351,17 +351,17 @@ kgit-meta is the actual application of feature description(s) to a kernel repo. In other words, it is responsible for interpreting the meta series generated from a scc compiled script. As a result, kgit-meta is coupled to the set of commands permitted in a .scc feature description (listed in the scc section). -kgit-meta understands both the meta series format and how to use git and -guilt to modify a base git repository. It processes a meta-series line by +kgit-meta understands both the meta series format and how to use Git and +guilt to modify a base Git repository. It processes a meta-series line by line, branching, tagging, patching and tracking changes that are made to the -base git repository. +base Git repository. Once kgit-meta has processed a meta-series, it leaves the repository with the last branch checked out, and creates the necessary guilt infrastructure to inspect the tree, or add to it via using guilt. As was previously mentioned, guilt is not required, but is provided as a convenience. Other utilities such -as quilt, stgit, git or others can also be used to manipulate the git +as quilt, stgit, Git or others can also be used to manipulate the Git repository. --> @@ -370,12 +370,12 @@ repository. Workflow Examples - As previously noted, the Yocto Project kernel has built in git integration. + As previously noted, the Yocto Project kernel has built in Git integration. However, these utilities are not the only way to work with the kernel repository. - Yocto Project has not made changes to git or to other tools that + Yocto Project has not made changes to Git or to other tools that would invalidate alternate workflows. Additionally, the way the kernel repository is constructed results in using - only core git functionality thus allowing any number of tools or front ends to use the + only core Git functionality thus allowing any number of tools or front ends to use the resulting tree. @@ -404,7 +404,7 @@ repository. A more efficient way to determine what has changed in the kernel is to use - git and inspect or search the kernel tree. + Git and inspect or search the kernel tree. This method gives you a full view of not only the source code modifications, but also provides the reasons for the changes. @@ -413,8 +413,8 @@ repository. What Changed in a BSP? - Following are a few examples that show how to use git to examine changes. - Note that because the Yocto Project git repository does not break existing git + Following are a few examples that show how to use Git to examine changes. + Note that because the Yocto Project Git repository does not break existing Git functionality and because there exists many permutations of these types of commands there are many more methods to discover changes. @@ -477,7 +477,7 @@ repository. You can use many other comparisons to isolate BSP changes. For example, you can compare against kernel.org tags (e.g. v2.6.27.18, etc), or - you can compare against subsystems (e.g. git whatchanged mm). + you can compare against subsystems (e.g. git whatchanged mm). @@ -492,9 +492,9 @@ repository. - Since the Yocto Project kernel source tree is backed by git, this activity is + Since the Yocto Project kernel source tree is backed by Git, this activity is much easier as compared to with previous releases. - Because git tracks file modifications, additions and deletions, it is easy + Because Git tracks file modifications, additions and deletions, it is easy to modify the code and later realize that the changes should be saved. It is also easy to determine what has changed. This method also provides many tools to commit, undo and export those modifications. @@ -507,7 +507,7 @@ repository. Bulk storage - Internal sharing either through patches or by using git + Internal sharing either through patches or by using Git External submissions Exporting for integration into another SCM @@ -555,7 +555,7 @@ repository. The previous operations capture all the local changes in the project source - tree in a single git commit. + tree in a single Git commit. And, that commit is also stored in the project's source tree. @@ -575,12 +575,12 @@ repository. The examples in this section assume that changes have been incrementally committed to the tree during development and now need to be exported. The sections that follow describe how you can export your changes internally through either patches or by - using git commands. + using Git commands. During development the following commands are of interest. - For full git documentation, refer to the git man pages or to an online resource such + For full Git documentation, refer to the Git man pages or to an online resource such as . @@ -619,15 +619,15 @@ repository. associated with development by using the following commands: - > git add >path</file - > git commit --amend - > git rebase or git rebase -i + > Git add >path</file + > Git commit --amend + > Git rebase or Git rebase -i Again, assuming that the changes have not been pushed upstream, and that - no pending works-in-progress exist (use "git status" to check) then + no pending works-in-progress exist (use git status to check) then you can revert (undo) commits by using the following commands: @@ -642,13 +642,13 @@ repository. - You can create branches, "cherry-pick" changes or perform any number of git + You can create branches, "cherry-pick" changes or perform any number of Git operations until the commits are in good order for pushing upstream or for pull requests. After a push or pull, commits are normally considered "permanent" and you should not modify them. If they need to be changed you can incrementally do so with new commits. - These practices follow the standard "git" workflow and the kernel.org best + These practices follow the standard Git workflow and the kernel.org best practices, which Yocto Project recommends. @@ -717,7 +717,7 @@ repository.
- Exporting Changes Internally by Using git + Exporting Changes Internally by Using Git This section describes how you can export changes from a working directory @@ -743,20 +743,20 @@ repository. - A pull request entails using "git request-pull" to compose an email to the + A pull request entails using git request-pull to compose an email to the maintainer requesting that a branch be pulled into the master repository, see for an example. - Other commands such as 'git stash' or branching can also be used to save + Other commands such as git stash or branching can also be used to save changes, but are not covered in this document.
@@ -787,7 +787,7 @@ repository. The messages used to commit changes are a large part of these standards. Consequently, be sure that the headers for each commit have the required information. If the initial commits were not properly documented or do not meet those standards, - you can re-base by using the "git rebase -i" command to manipulate the commits and + you can re-base by using the git rebase -i command to manipulate the commits and get them into the required format. Other techniques such as branching and cherry-picking commits are also viable options. @@ -795,7 +795,7 @@ repository. Once you complete the commits, you can generate the email that sends the patches to the maintainer(s) or lists that review and integrate changes. - The command "git send-email" is commonly used to ensure that patches are properly + The command git send-email is commonly used to ensure that patches are properly formatted for easy application and avoid mailer-induced patch damage. @@ -827,7 +827,7 @@ repository. - Many SCMs can directly import git commits, or can translate git patches so that + Many SCMs can directly import Git commits, or can translate Git patches so that information is not lost. Those facilities are SCM-dependent and you should use them whenever possible. @@ -856,7 +856,7 @@ repository. Depending on the SCM it might be possible to export the entire Yocto Project - kernel git repository, branches and all, into a new environment. + kernel Git repository, branches and all, into a new environment. This method is preferred because it has the most flexibility and potential to maintain the meta data associated with each commit. @@ -902,14 +902,14 @@ repository. automatically apply them to the kernel during patching. -- cgit v1.2.3-54-g00ecf