<!-- <listitem><para>Series & Configuration Compiler</para></listitem>
<listitem><para>kgit</para></listitem> -->
<listitem><para>Workflow examples</para></listitem>
- <listitem><para>Source Code Manager (SCM)</para></listitem>
-<!-- <listitem><para>Board Support Package (BSP) template migration</para></listitem> -->
+
<!-- <listitem><para>Source Code Manager (SCM)</para></listitem>
+ <listitem><para>Board Support Package (BSP) template migration</para></listitem>
<listitem><para>BSP creation</para></listitem>
<listitem><para>Patching</para></listitem>
<listitem><para>Updating BSP patches and configuration</para></listitem>
-
<!-- <listitem><para>guilt</para></listitem>
- <listitem><para>scc file example</para></listitem> -->
+ <listitem><para>guilt</para></listitem>
+ <listitem><para>scc file example</para></listitem>
<listitem><para>"dirty" string</para></listitem>
-
<!-- <listitem><para>Transition kernel layer</para></listitem> -->
+ <listitem><para>Transition kernel layer</para></listitem> -->
</itemizedlist>
</para>
</section>
<section id='tree-construction'>
<title>Tree Construction</title>
<para>
-The Yocto Project kernel repository, as shipped with the product, is created by
-compiling and executing the set of feature descriptions for every BSP/feature
-in the product. Those feature descriptions list all necessary patches,
-configuration, branching, tagging and feature divisions found in the kernel.
-</para>
-<para>
-The files used to describe all the valid features and BSPs in the Yocto Project
-kernel can be found in any clone of the kernel git tree. The directory
-wrs/cfg/kernel-cache/ is a snapshot of all the kernel configuration and
-feature descriptions (.scc) that were used to build the kernel repository.
-It should however be noted, that browsing the snapshot of feature
-descriptions and patches is not an effective way to determine what is in a
-particular kernel branch. Using git directly to get insight into the changes
-in a branch is more efficient and a more flexible way to inspect changes to
-the kernel. Examples of using git to inspect kernel commits are in the
-following sections.
-</para>
-<para>
-As a reminder, it is envisioned that a ground up reconstruction of the
-complete kernel tree is an action only taken by Yocto Project team during an
-active development cycle. When an end user creates a project, it takes
-advantage of this complete tree in order to efficiently place a git tree
-within their project.
-</para>
-<para>
-The general flow of the project specific kernel tree construction is as follows:
-<orderedlist>
- <listitem><para>a top level kernel feature is passed to the kernel build subsystem,
- normally this is a BSP for a particular kernel type.</para></listitem>
-
- <listitem><para>the file that describes the top level feature is located by searching
- system directories:</para>
-
- <itemizedlist>
- <listitem><para>the kernel-cache under linux/wrs/cfg/kernel-cache</para></listitem>
-<!-- <listitem><para>kernel-*-cache directories in layers</para></listitem> -->
- <listitem><para>recipe SRC_URIs</para></listitem>
-<!-- <listitem><para>configured and default templates</para></listitem> -->
- </itemizedlist>
+ The Yocto Project kernel repository, as shipped with the product, is created by
+ compiling and executing the set of feature descriptions for every BSP/feature
+ in the product.
+ Those feature descriptions list all necessary patches,
+ configuration, branching, tagging and feature divisions found in the kernel.
+ </para>
+ <para>
+ 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.
+ The directory <filename>wrs/cfg/kernel-cache/</filename> 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
+ in a branch.
+ Using git is a 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.
+ </para>
+ <note><para>
+ Ground up reconstruction of the complete kernel tree is an action only taken by the
+ Yocto Project team during an active development cycle.
+ Creating a project takes advantage of this complete tree in order to
+ place efficiently a git tree within the project.
+ </para></note>
+ <para>
+ The general flow for constructing a project-specific kernel tree is as follows:
+ <orderedlist>
+ <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
+ Normally, this is a BSP for a particular kernel type.</para></listitem>
- <para>In a typical build a feature description of the format:
- <bsp name>-<kernel type>.scc is the target of the search.
- </para></listitem>
+ <listitem><para>The file that describes the top-level feature is located by searching
+ these system directories:</para>
- <listitem><para>once located, the feature description is compiled into a simple script
- of actions, or an existing equivalent script which was part of the
- shipped kernel is located.</para></listitem>
+ <itemizedlist>
+ <listitem><para>The kernel-cache under
+ <filename>linux/wrs/cfg/kernel-cache</filename></para></listitem>
+<!-- <listitem><para>kernel-*-cache directories in layers</para></listitem> -->
+ <listitem><para>Recipe SRC_URIs</para></listitem>
+<!-- <listitem><para>configured and default templates</para></listitem> -->
+ </itemizedlist>
- <listitem><para>extra features are appended to the top level feature description. Extra
- features can come from the KERNEL_FEATURES variable in recipes.</para></listitem>
+ <para>For a typical build a feature description of the format:
+ <bsp name>-<kernel type>.scc is the target of the search.
+ </para></listitem>
- <listitem><para>each extra feature is located, compiled and appended to the script from
- step #3</para></listitem>
+ <listitem><para>Once located, the feature description is either compiled into a simple script
+ of actions, or an existing equivalent script that was part of the
+ shipped kernel is located.</para></listitem>
- <listitem><para>the script is executed, and a meta-series is produced. The meta-series
- is a description of all the branches, tags, patches and configuration that
- need to be applied to the base git repository to completely create the
- "bsp_name-kernel_type".</para></listitem>
+ <listitem><para>Extra features are appended to the top-level feature description.
+ These features can come from the KERNEL_FEATURES variable in recipes.</para></listitem>
- <listitem><para>the base repository is cloned, and the actions
- listed in the meta-series are applied to the tree.</para></listitem>
+ <listitem><para>Each extra feature is located, compiled and appended to the script from
+ step #3</para></listitem>
- <listitem><para>the git repository is left with the desired branch checked out and any
- required branching, patching and tagging has been performed.</para></listitem>
-</orderedlist>
-</para>
+ <listitem><para>The script is executed, and a meta-series is produced.
+ The meta-series is a description of all the branches, tags, patches and configuration that
+ needs to be applied to the base git repository to completely create the
+ "bsp_name-kernel_type".</para></listitem>
-<para>
-The tree is now ready for configuration and compilation. Those two topics will
-be covered below.
-</para>
+ <listitem><para>The base repository is cloned, and the actions
+ listed in the meta-series are applied to the tree.</para></listitem>
-<note><para>The end user generated meta-series adds to the kernel as shipped with
- the Yocto Project release. Any add-ons and configuration data are applied
- to the end of an existing branch. The full repository generation that
- is found in the linux-2.6-windriver.git is the combination of all
- supported boards and configurations.
-</para></note>
+ <listitem><para>The git repository is left with the desired branch checked out and any
+ required branching, patching and tagging has been performed.</para></listitem>
+ </orderedlist>
+ </para>
-<para>
-This technique is flexible and allows the seamless blending of an immutable
-history with additional deployment specific patches. Any additions to the
-kernel become an integrated part of the branches.
-</para>
+ <para>
+ The tree is now ready for configuration and compilation.
+ </para>
+
+ <note><para>The end-user generated meta-series adds to the kernel as shipped with
+ the Yocto Project release.
+ Any add-ons and configuration data are applied to the end of an existing branch.
+ The full repository generation that is found in the
+ <filename>linux-2.6-windriver.git</filename> is the combination of all
+ supported boards and configurations.</para>
+
+ <para>This technique is flexible and allows the seamless blending of an immutable
+ history with additional deployment specific patches.
+ Any additions to the kernel become an integrated part of the branches.
+ </para></note>
<!-- <note><para>It is key that feature descriptions indicate if any branches are
required, since the build system cannot automatically decide where a
</para>
</note> -->
-<para>
+<!-- <para>
A summary of end user tree construction activities follow:
<itemizedlist>
<listitem><para>compile and link a full top-down kernel description from feature descriptions</para></listitem>
<listitem><para>migrate configuration fragments and configure the kernel</para></listitem>
<listitem><para>checkout the BSP branch and build</para></listitem>
</itemizedlist>
-</para>
+</para> -->
</section>
<section id='build-strategy'>
<title>Build Strategy</title>
-<para>
-There are some prerequisites that must be met before starting the compilation
-phase of the kernel build system:
-</para>
-<itemizedlist>
- <listitem><para>There must be a kernel git repository indicated in the SRC_URI.</para></listitem>
- <listitem><para>There must be a branch <bsp name>-<kernel type>.</para></listitem>
-</itemizedlist>
+ <para>
+ There are some prerequisites that must be met before starting the compilation
+ phase of the kernel build system:
+ </para>
-<para>
-These are typically met by running tree construction/patching phase of the
-build system, but can be achieved by other means. Examples of alternate work
-flows such as bootstrapping a BSP are provided below.
-</para>
-<para>
-Before building a kernel it is configured by processing all of the
-configuration "fragments" specified by the scc feature descriptions. As the
-features are compiled, associated kernel configuration fragments are noted
-and recorded in the meta-series in their compilation order. The
-fragments are migrated, pre-processed and passed to the Linux Kernel
-Configuration subsystem (lkc) as raw input in the form of a .config file.
-The lkc uses its own internal dependency constraints to do the final
-processing of that information and generates the final .config that will
-be used during compilation.
-</para>
-<para>
-Kernel compilation is started, using the board's architecture and other
-relevant values from the board template, and a kernel image is produced.
-</para>
-<para>
-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.
-This build dir will be called "linux-<BSPname>-<kerntype>-build" where
-kerntype is one of standard kernel types. This functionality is done by making
-use of the existing support that is within the kernel.org tree by default.
-</para>
-<para>
-What this means, is that all the generated files (that includes the final
-".config" itself, all ".o" and ".a" etc) are now in this directory. Since
-the git source tree can contain any number of BSPs, all on their own branch,
-you now can easily switch between builds of BSPs as well, since each one also
-has their own separate build directory.
-</para>
+ <itemizedlist>
+ <listitem><para>There must be a kernel git repository indicated in the SRC_URI.</para></listitem>
+ <listitem><para>There must be a branch <bsp name>-<kernel type>.</para></listitem>
+ </itemizedlist>
+
+ <para>
+ You can typically meet these prerequisites by running the tree construction/patching phase
+ of the build system.
+ However, other means do exist.
+ For examples of alternate workflows such as bootstrapping a BSP, see
+ the<link linkend='workflow-examples'> Workflow Examples</link> section in this manual.
+ </para>
+
+ <para>
+ Before building a kernel it is configured by processing all of the
+ configuration "fragments" specified by the scc feature descriptions.
+ As the features are compiled, associated kernel configuration fragments are noted
+ and recorded in the meta-series in their compilation order.
+ The fragments are migrated, pre-processed and passed to the Linux Kernel
+ Configuration subsystem (lkc) as raw input in the form of a <filename>.config</filename> file.
+ The lkc uses its own internal dependency constraints to do the final
+ processing of that information and generates the final <filename>.config</filename> file
+ that is used during compilation.
+ </para>
+
+ <para>
+ Using the board's architecture and other relevant values from the board's template
+ the Kernel compilation is started and a kernel image is produced.
+ </para>
+
+ <para>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.
+ This build tree has the name using the following form:
+ <literallayout class='monospaced'>
+ linux-<BSPname>-<kerntype>-build
+ </literallayout>
+ "kerntype" is one of the standard kernel types.
+ </para>
+
+ <para>
+ The existing support in the kernel.org tree achieves this default functionality.
+ </para>
+
+ <para>
+ What this means, is that all the generated files for a particular BSP are now in this directory.
+ The files include the final <filename>.config</filename>, all the <filename>.o</filename>
+ files, the <filename>.a</filename> 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.
+ </para>
</section>
<!-- <section id='scc'>
<title>Workflow Examples</title>
<para>
-As previously noted, the Yocto Project kernel has built in git/guilt
-integration, but these utilities are not the only way to work with the kernel
-repository. Yocto Project has not made changes to git, or other tools that
-invalidate alternate workflows. Additionally, the way the kernel repository
-is constructed uses only core git functionality allowing any number of tools
-or front ends to use the resulting tree.</para>
-<para>
-This section contains several workflow examples.
-</para>
+ As previously noted, the Yocto Project kernel has built in git/guilt
+ 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
+ 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
+ resulting tree.
+ </para>
+
+ <para>
+ This section contains several workflow examples.
+ </para>
<section id='change-inspection-kernel-changes-commits'>
<title>Change Inspection: Kernel Changes/Commits</title>
-<para>
-A common question when working with a BSP/kernel is: "What changes have been applied to this tree?"
-</para>
-<para>
-In some projects, where a collection of directories that
-contained patches to the kernel, those patches could be inspected, grep'd or
-otherwise used to get a general feeling for changes. This sort of patch
-inspection is not an efficient way to determine what has been done to the
-kernel, since there are many optional patches that are selected based on the
-kernel type and feature description, not to mention patches that are actually
-in directories that are not being searched.
-</para>
-<para>
-A more effective way to determine what has changed in the kernel is to use
-git and inspect / search the kernel tree. This is a full view of not only the
-source code modifications, but the reasoning behind the changes.
-</para>
+
+ <para>
+ A common question when working with a BSP or kernel is:
+ "What changes have been applied to this tree?"
+ </para>
+
+ <para>
+ In projects that have a collection of directories that
+ contain patches to the kernel it is possible to inspect or "grep" the contents
+ of the directories to get a general feel for the changes.
+ This sort of patch inspection is not an efficient way to determine what has been done to the
+ kernel.
+ The reason it is inefficient is because there are many optional patches that are
+ selected based on the kernel type and the feature description.
+ Additionally, patches could exist in directories that are not included in the search.
+ </para>
+
+ <para>
+ A more efficient way to determine what has changed in the kernel is to use
+ 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.
+ </para>
+
<section id='what-changed-in-a-bsp'>
<title>What Changed in a BSP?</title>
-<para>
-These examples could continue for some time, since the Yocto Project git
-repository doesn't break existing git functionality and there are nearly
-endless permutations of those commands. Also note that unless a commit range
-is given (<kernel type>..<bsp>-<kernel type>), kernel.org history is blended
-with Yocto Project changes
-</para>
-<literallayout class='monospaced'>
+
+ <para>
+ 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.
+ </para>
+
+ <note><para>
+ Unless you provide a commit range
+ (<kernel-type>..<bsp>-<kernel-type>), kernel.org history
+ is blended with Yocto Project changes.
+ </para></note>
+
+ <literallayout class='monospaced'>
# full description of the changes
> git whatchanged <kernel type>..<bsp>-<kernel type>
> eg: git whatchanged standard..common_pc-standard
# summary of the changes
- > git log ‐‐pretty=oneline ‐‐abbrev-commit <kernel type>..<bsp>-<kernel type>
+ > git log --pretty=oneline --;abbrev-commit <kernel type>..<bsp>-<kernel type>
# source code changes (one combined diff)
> git diff <kernel type>..<bsp>-<kernel type>
# determine the commits which touch each line in a file
> git blame <path to file>
-</literallayout>
+ </literallayout>
</section>
<section id='show-a-particular-feature-or-branch-change'>
<title>Show a Particular Feature or Branch Change</title>
-<para>
-Significant features or branches are tagged in the Yocto Project tree to divide
-changes. Remember to first determine (or add) the tag of interest. Note:
-there will be many tags, since each BSP branch is tagged, kernel.org tags and
-feature tags are all present.
-</para>
-<literallayout class='monospaced'>
+
+ <para>
+ Significant features or branches are tagged in the Yocto Project tree to divide
+ changes.
+ Remember to first determine (or add) the tag of interest.
+ </para>
+
+ <note><para>
+ Because BSP branch, kernel.org, and feature tags are all present, there are many tags.
+ </para></note>
+
+ <literallayout class='monospaced'>
# show the changes tagged by a feature
> git show <tag>
> eg: git show yaffs2
# determine which branches contain a feature
- > git branch ‐‐contains <tag>
+ > git branch --contains <tag>
# show the changes in a kernel type
> git whatchanged wrs_base..<kernel type>
> eg: git whatchanged wrs_base..standard
-</literallayout>
-<para>
-Many other comparisons can be done to isolate BSP changes, such as comparing
-to kernel.org tags (v2.6.27.18, etc), per subsystem comparisons (git
-whatchanged mm) or many other types of checks.
-</para>
+ </literallayout>
+
+ <para>
+ 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 agains subsystems (e.g. git whatchanged mm).
+ </para>
</section>
</section>
<section id='development-saving-kernel-modifications'>
<title>Development: Saving Kernel Modifications</title>
-<para>
-Another common operation is to build a Yocto Project supplied BSP, make some
-changes, rebuild and test. Those local changes often need to be exported,
-shared or otherwise maintained.
-</para>
-<para>
-Since the Yocto Project kernel source tree is backed by git, this activity is
-greatly simplified and is much easier than in previous releases. git tracks
-file modifications, additions and deletions, which allows the developer to
-modify the code and later realize that the changes should be saved, and
-easily determine what was changed. It also provides many tools to commit,
-undo and export those modifications.
-</para>
-<para>
-There are many ways to perform this action, and the technique employed
-depends on the destination for the patches, which could be any of:
-<itemizedlist>
- <listitem><para>bulk storage</para></listitem>
- <listitem><para>internal sharing either through patches or using git</para></listitem>
- <listitem><para>external submission</para></listitem>
- <listitem><para>export for integration into another SCM</para></listitem>
-</itemizedlist>
-</para>
-<para>
-The destination of the patches also incluences the method of gathering them
-due to issues such as:
-<itemizedlist>
- <listitem><para>bisectability</para></listitem>
- <listitem><para>commit headers</para></listitem>
- <listitem><para>division of subsystems for separate submission / review</para></listitem>
-</itemizedlist>
-</para>
+
+ <para>
+ Another common operation is to build a BSP supplied by Yocto Project, make some
+ changes, rebuild and then test.
+ Those local changes often need to be exported, shared or otherwise maintained.
+ </para>
+
+ <para>
+ 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
+ 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.
+ </para>
+
+ <para>
+ There are many ways to save kernel modifications.
+ The technique employed
+ depends on the destination for the patches:
+
+ <itemizedlist>
+ <listitem><para>Bulk storage</para></listitem>
+ <listitem><para>Internal sharing either through patches or by using git</para></listitem>
+ <listitem><para>External submissions</para></listitem>
+ <listitem><para>Exporting for integration into another SCM</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Because of the following list of issues, the destination of the patches also influences
+ the method for gathering them:
+
+ <itemizedlist>
+ <listitem><para>Bisectability</para></listitem>
+ <listitem><para>Commit headers</para></listitem>
+ <listitem><para>Division of subsystems for separate submission or review</para></listitem>
+ </itemizedlist>
+ </para>
<section id='bulk-export'>
<title>Bulk Export</title>
-<para>
-If patches are simply being stored outside of the kernel source repository,
-either permanently or temporarily, then there are several methods that can be
-used.
-</para>
-<para>
-Note the "bulk" in this discussion, these techniques are not appropriate for
-full integration of upstream submission, since they do not properly divide
-changes or provide an avenue for per-change commit messages. This example
-assumes that changes have not been committed incrementally during development
-and simply must be gathered and exported.
-<literallayout class='monospaced'>
+
+ <para>
+ This section describes how you can export in "bulk" changes that have not
+ been separated or divided.
+ This situation works well when you are simply storing patches outside of the kernel
+ source repository, either permanently or temporarily, and you are not committing
+ incremental changes during development.
+ </para>
+
+ <note><para>
+ This technique is not appropriate for full integration of upstream submission
+ because changes are not properly divided and do not provide an avenue for per-change
+ commit messages.
+ Therefore, this example assumes that changes have not been committed incrementally
+ during development and that you simply must gather and export them.
+ </para></note>
+
+ <literallayout class='monospaced'>
# bulk export of ALL modifications without separation or division
# of the changes
> git commit -s -a -m >commit message<
or
> git commit -s -a # and interact with $EDITOR
-</literallayout>
-</para>
-<para>
-These operations have captured all the local changes in the project source
-tree in a single git commit, and that commit is also stored in the project's
-source tree.
-</para>
-<para>
-Once exported, those changes can then be restored manually, via a template or
-through integration with the default_kernel. Those topics are covered in
-future sections.
-</para>
+ </literallayout>
+
+ <para>
+ The previous operations capture all the local changes in the project source
+ tree in a single git commit.
+ And, that commit is also stored in the project's source tree.
+ </para>
+
+ <para>
+ Once the changes are exported, you can restore them manually using a template
+ or through integration with the <filename>default_kernel</filename>.
+ </para>
+
</section>
<section id='incremental-planned-sharing'>
<title>Incremental/Planned Sharing</title>
-<para>
-Note: unlike the previous "bulk" section, the following examples assume that
-changes have been incrementally committed to the tree during development and
-now are being exported.
-</para>
-<para>
-During development the following commands will be of interest, but for full
-git documentation refer to the git man pages or an online resource such as
-http://github.com
-<literallayout class='monospaced'>
+
+ <para>
+ This section describes how to save modifications when you are making incremental
+ commits or practicing planned sharing.
+ 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.
+ </para>
+
+ <para>
+ During development the following commands are of interest.
+ For full git documentation, refer to the git man pages or to an online resource such
+ as <ulink url='http://github.com'></ulink>.
+
+ <literallayout class='monospaced'>
# edit a file
> vi >path</file
# stage the change
> git commit -s
... etc.
-</literallayout>
-</para>
-<para>
-Distributed development with git is possible by having a universally agreed
-upon unique commit identifier (set by the creator of the commit) mapping to a
-specific changeset with a specific parent. This ID is created for you when
-you create a commit, and will be re-created when you amend/alter or re-apply
-a commit. As an individual in isolation, this is of no interest, but if you
-intend to share your tree with normal git push/pull operations for
-distributed development, you should consider the ramifications of changing a
-commit that you've already shared with others.
-</para>
-<para>
-Assuming that the changes have *not* been pushed upstream, or pulled into
-another repository, both the commit content and commit messages associated
-with development can be update via:
-<literallayout class='monospaced'>
+ </literallayout>
+ </para>
+
+ <para>
+ Distributed development with git is possible when you use a universally
+ agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
+ specific changeset with a specific parent.
+ This identifier is created for you when
+ you create a commit, and is re-created when you amend, alter or re-apply
+ a commit.
+ As an individual in isolation, this is of no interest.
+ However, if you
+ intend to share your tree with normal git push and pull operations for
+ distributed development, you should consider the ramifications of changing a
+ commit that you have already shared with others.
+ </para>
+
+ <para>
+ Assuming that the changes have not been pushed upstream, or pulled into
+ another repository, you can update both the commit content and commit messages
+ associated with development by using the following commands:
+
+ <literallayout class='monospaced'>
> git add >path</file
- > git commit ‐‐amend
+ > git commit --amend
> git rebase or git rebase -i
-</literallayout>
-</para>
-<para>
-Again, assuming that the changes have *not* been pushed upstream, and that
-there are no pending works in progress (use "git status" to check) then
-commits can be reverted (undone) via:
-<literallayout class='monospaced'>
+ </literallayout>
+ </para>
+
+ <para>
+ Again, assuming that the changes have not been pushed upstream, and that
+ no pending works-in-progress exist (use "git status" to check) then
+ you can revert (undo) commits by using the following commands:
+
+ <literallayout class='monospaced'>
# remove the commit, update working tree and remove all
# traces of the change
- > git reset ‐‐hard HEAD^
+ > git reset --hard HEAD^
# remove the commit, but leave the files changed and staged for re-commit
- > git reset ‐‐soft HEAD^
+ > git reset --soft HEAD^
# remove the commit, leave file change, but not staged for commit
- > git reset ‐‐mixed HEAD^
-</literallayout>
-</para>
-<para>
-Branches can be created, changes cherry-picked or any number of git
-operations performed until the commits are in good order for pushing upstream
-or pull requests. After a push or pull, commits are normally considered
-'permanent' and should not be modified, only incrementally changed in new
-commits. This is standard "git" workflow and Yocto Project recommends the
-kernel.org best practices.
-</para>
-<note><para>It is recommend to tag or branch before adding changes to a Yocto Project
- BSP (or creating a new one), since the branch or tag provides a
- reference point to facilitate locating and exporting local changes.
-</para></note>
+ > git reset --mixed HEAD^
+ </literallayout>
+ </para>
+
+ <para>
+ 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
+ practices, which Yocto Project recommends.
+ </para>
+
+ <note><para>
+ It is recommend to tag or branch before adding changes to a Yocto Project
+ BSP or before creating a new one.
+ The reason for this recommendation is because the branch or tag provides a
+ reference point to facilitate locating and exporting local changes.
+ </para></note>
<section id='export-internally-via-patches'>
- <title>Export Internally Via Patches</title>
-<para>
-Committed changes can be extracted from a working directory by exporting them
-as patches. Those patches can be used for upstream submission, placed in a
-Yocto Project template for automatic kernel patching or many other common uses.
-
-<literallayout class='monospaced'>
- # >first commit> can be a tag if one was created before development
+ <title>Exporting Changes Internally by Using Patches</title>
+
+ <para>
+ This section describes how you can extract committed changes from a working directory
+ by exporting them as patches.
+ Once extracted, you can use the patches for upstream submission,
+ place them in a Yocto Project template for automatic kernel patching,
+ or apply them in many other common uses.
+ </para>
+
+ <para>
+ This example shows how to create a directory with sequentially numbered patches.
+ Once the directory is created, you can apply it to a repository using the
+ <filename>git am</filename> command to reproduce the original commit and all
+ the related information such as author, date, commit log, and so forth.
+ </para>
+
+ <note><para>
+ The new commit identifiers (ID) will be generated upon re-application.
+ This action reflects that the commit is now applied to an underlying commit
+ with a different ID.
+ </para></note>
+
+ <para>
+ <literallayout class='monospaced'>
+ # <first-commit> can be a tag if one was created before development
# began. It can also be the parent branch if a branch was created
# before development began.
> git format-patch -o <dir> <first commit>..<last commit>
-</literallayout>
-</para>
+ </literallayout>
+ </para>
-<para>
- In other words:
-<literallayout class='monospaced'>
- # identify commits of interest.
+ In other words:
+ <literallayout class='monospaced'>
+ # Identify commits of interest.
- # if the tree was tagged before development
+ # If the tree was tagged before development
> git format-patch -o <save dir> <tag>
- # if no tags are available
+ # If no tags are available
> git format-patch -o <save dir> HEAD^ # last commit
> git format-patch -o <save dir> HEAD^^ # last 2 commits
> git whatchanged # identify last commit
> git format-patch -o <save dir> <commit id>
> git format-patch -o <save dir> <rev-list>
-</literallayout>
-</para>
+ </literallayout>
+ </para>
-<para>
-The result is a directory with sequentially numbered patches, that when
-applied to a repository using "git am", will reproduce the original commit
-and all related information (author, date, commit log, etc) will be
-preserved. Note that new commit IDs will be generated upon reapplication,
-reflecting that the commit is now applied to an underlying commit with a
-different ID.
-</para>
-<!--<para>
-See the "template patching" example for how to use the patches to
-automatically apply to a new kernel build.
-</para> -->
- </section>
+ <!--<para>
+ See the "template patching" example for how to use the patches to
+ automatically apply to a new kernel build.
+ </para>-->
+ </section>
<section id='export-internally-via-git'>
- <title>Export Internally Via git</title>
-<para>
-Committed changes can also be exported from a working directory by pushing
-(or by making a pull request) the changes into a master repository. Those
-same change can then be pulled into a new kernel build at a later time using this command form:
-<literallayout class='monospaced'>
+ <title>Exporting Changes Internally by Using git</title>
+
+ <para>
+ This section describes how you can export changes from a working directory
+ by pushing the changes into a master repository or by making a pull request.
+ Once you have pushed the changes in the master repository you can then
+ pull those same changes into a new kernel build at a later time.
+ </para>
+
+ <para>
+ Use this command form to push the changes:
+ <literallayout class='monospaced'>
git push ssh://<master server>/<path to repo> <local branch>:<remote branch>
-</literallayout>
-For example:
-<literallayout class='monospaced'>
+ </literallayout>
+ </para>
+
+ <para>
+ For example, the following command pushes the changes from your local branch
+ <filename>common_pc-standard</filename> to the remote branch with the same name
+ in the master repository <filename>//git.mycompany.com/pub/git/kernel-2.6.27</filename>.
+ <literallayout class='monospaced'>
> push ssh://git.mycompany.com/pub/git/kernel-2.6.27 common_pc-standard:common_pc-standard
-</literallayout>
-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
-http://github.com/guides/pull-requests for an example.
-</para>
-<para>
-Other commands such as 'git stash' or branching can also be used to save
-changes, but are not covered in this document.
-</para>
-<para>
-See the section "importing from another SCM" for how a git push to the
-default_kernel, can be used to automatically update the builds of all users
-of a central git repository.
-</para>
- </section>
+ </literallayout>
+ </para>
+
+ <para>
+ 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
+ <ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
+ </para>
+
+ <note><para>
+ Other commands such as 'git stash' or branching can also be used to save
+ changes, but are not covered in this document.
+ </para></note>
+
+ <!--<para>
+ See the section "importing from another SCM" for how a git push to the
+ default_kernel, can be used to automatically update the builds of all users
+ of a central git repository.
+ </para>-->
+ </section>
</section>
<section id='export-for-external-upstream-submission'>
An example of dumping patches for external submission follows:
<literallayout class='monospaced'>
# dump the last 4 commits
- > git format-patch ‐‐thread -n -o ~/rr/ HEAD^^^^
- > git send-email ‐‐compose ‐‐subject '[RFC 0/N] <patch series summary>' \
- ‐‐to foo@yoctoproject.org ‐‐to bar@yoctoproject.org \
- ‐‐cc list@yoctoproject.org ~/rr
+ > git format-patch --thread -n -o ~/rr/ HEAD^^^^
+ > git send-email --compose --subject '[RFC 0/N] <patch series summary>' \
+ --to foo@yoctoproject.org --to bar@yoctoproject.org \
+ --cc list@yoctoproject.org ~/rr
# the editor is invoked for the 0/N patch, and when complete the entire
# series is sent via email for review
</literallayout>
So first create a bare clone of the Yocto Project git repository, and then create a
local clone of that:
<literallayout class='monospaced'>
- $ git clone ‐‐bare git://git.pokylinux.org/linux-2.6-windriver.git
+ $ git clone --bare git://git.pokylinux.org/linux-2.6-windriver.git
linux-2.6-windriver.git
$ git clone linux-2.6-windriver.git linux-2.6-windriver
</literallayout>
