No modification to the original content. Cc: Jani Nikula <jani.nikula@xxxxxxxxx> Cc: Daniel Vetter <daniel.vetter@xxxxxxxx> Signed-off-by: Rodrigo Vivi <rodrigo.vivi@xxxxxxxxx> --- index.rst | 1 + qf | 282 +++++--------------------------------------------------------- qf.rst | 250 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 274 insertions(+), 259 deletions(-) create mode 100644 qf.rst diff --git a/index.rst b/index.rst index 0b9df594733d..f5f8e95571eb 100644 --- a/index.rst +++ b/index.rst @@ -9,6 +9,7 @@ Contents: drm-misc drm-intel dim + qf TODO Indices and tables diff --git a/qf b/qf index 883dda0a1668..1f056f90ef70 100755 --- a/qf +++ b/qf @@ -169,6 +169,28 @@ function quilt_clean_check fi } +function qf_help +{ + manpage=$DIM_PREFIX/maintainer-tools/qf.rst + if [ ! -e "$manpage" ]; then + manpage=$(dirname $(readlink -f $0))/qf.rst + if [ ! -e "$manpage" ]; then + echo "Can't find the man page." + exit 1 + fi + fi + + if hash rst2man 2>/dev/null; then + renderer=rst2man + pager="man -l -" + else + renderer=cat + pager=${PAGER:-cat} + fi + + $renderer < $manpage | $pager +} + case "$1" in setup) cd `git rev-parse --show-toplevel` @@ -459,265 +481,7 @@ case "$1" in gitk "$@" ;; help) - if hash rst2man 2>/dev/null; then - renderer=rst2man - pager="man -l -" - else - renderer=cat - pager=${PAGER:-cat} - fi - $renderer <<HERE | $pager -==== - qf -==== - ---------------------- -quilt git flow script ---------------------- - -:Author: Daniel Vetter <daniel.vetter@xxxxxxxx> -:Date: 2014-05-15 -:Copyright: 2013-2014 Intel Corporation -:Manual section: 1 -:Manual group: maintainer tools - -SYNOPSIS -======== - -**qf** *command* [*arg* ...] - -DESCRIPTION -=========== - -**qf** is a workflow script to manage a quilt patch pile on top of a -git baseline and track any changes in git itself. The quilt -patches and any other metadata is tracked in git refs outside of -the normal tag/branch namespace. The current baseline (as a git -commit sha1) of the quilt patch pile is also tracked. An -integral part is support to export the quilt patch to an git -branch in the baseline repository and push/fetch changes to the -remote linked to this branch. - -Assuming there's already a branch "test" set up to track a -remote a quickstart overview (output omitted): - -Getting started ---------------- -$ qf setup test - -$ qf checkout test - -This automatically either creates a new, empty patch pile or -checks out the state of an existing remote. - -Note that this only initializes the quilt side of things and -presumes that the test branch is set up already, including -remote tracking connection. To create a completely new branch -hence first run - -$ git checkout -b test --track origin/test - -Committing changes and publishing the resulting git tree --------------------------------------------------------- -$ qf git gui # commit any changes in the patch directory - -$ qf export && qf push - -Rebasing --------- -$ qf baseline # print old baseline commit - -$ qf rebase upstream - -$ qf baseline # check new baseline commit - -Following changes in upstream ------------------------------ -$ qf fetch - -$ qf git pull && qf checkout test - -Doing only a git pull on the quilt branch leads to an -inconsitent state if the baseline changed. - -Bisecting patch history ------------------------ - -Git history in the patches directory records every rebase or any other changes -to the patch pile, including the baseline. Which means it can be used for -bisecting not just the individual patches, but the history of the entire patch -pile: - -$ qf git bisect *old-sha1* *new-sha1* - -to start the bisect process, and then for each bisect step: - -$ qf checkout HEAD - -Run tests to figure out whether it's part of the new (bad) or old (good) -history, then tell git using - -$ qf git bisect new|old - -COMMANDS -======== - -setup [*branch-name*] ---------------------- -Sets up a git repository for this quilt worflow script by -creating and initializing (if this isn't done yet) the git -repository in <git-root>/patches. - -If a branch name is given it must exist in the baseline -repository. If so a quilt branch of the same name with -$QUILT_PREFIX is created and initialized (but without any -patches). The remote configuration is copied over from the -branch in the baseline repository. The script will fall over if -the branch in the baseline repository doesn't have a remote -properly set up. - -If the quilt branch already exists in the remote the quilt then -it is initialized with the latest state (which is updated with -git fetch beforehand). The remote quilt branch must have the -same name as the branch in the local baseline repository, the -script doesn't support disparate tracking names for the quilt -branch. - -Before the newly created branch can be used it needs to be -checked out first. - -checkout|co *commit-ish|quilt-branch* -------------------------------------- -Checks out the given branch/commit-ish (same rules as for git -checkout apply) in the patches directory. If you want to check -out an earlier revision you might need to run qf fetch first to -make sure that the base repo has all the baseline refs. When -checking out a branch it's not necessary to add the -$QUILT_PREFIX (quilt/ by default) to the branch name, the script -will complete the name automatically. - -At the end all quilt patches will be pushed. Presuming the quilt -flow state hasn't been hand-edited or an incompletely pushed -quilt branch has been committed this will always succeed. - -rebase *commit-ish* -------------------- -Pops off all quilt patches, rebases the baseline to the given -commit and then reapplys all the quilt patches up to the same -patch as before. Then updates the BASELINE variable in -patches/config. - -clean-patches -------------- -Removes all unused patch files from the patches/ directory. - -refresh -------- -Refreshes all the quilt patches up to the currently applied -patch. Then it commits a wash-up commit with all the refreshed -patches. The command aborts if there are uncommited changes in -the patches repository. - -export ------- -Flattens the current quilt branch and exports it into the -respective git branch in the base tree. - -The reflog'ed QUILT_EXPORT is always updated with the result of -the export. This is useful to export when in the detached HEAD -state in the quilt repository hence there's no branch to export -to. - -export-visualize|ev -------------------- -Visualizes the latest export result using gitk, down to the -current baseline. - -push ----- -Exports the tree and then pushes both the quilt branch, the -exported branch and any new baselines to the respective remotes. - -fetch ------ -Fetches both the main and patches barnch remotes and pulls all -the baseline refs into the main repo. - -pull [--rebase] ---------------- - -First runs qf fetch and then updates the patches branch (with a git merge) and -the checks out the latest working copy. When given --rebase will rebase the -patches branch instead of merging. - -stage ------ -Resets the git index and then (re-)applies all currently applied -quilt patches to it. Useful to use git tools like git diff to -compare changes against the quilt patch state. - -wiggle-push|wp --------------- -Force-push the next patch and then wiggle in any conflicts. Does -not refresh the patch automatically, so that the conflict -resolution can be cross-checked. - -resolved --------- -Little helper when a patch conflict was resolved. First -refreshes the topmost patch, then fires up vim to edit the -headers. - -apply *patch-name* ------------------- -Adds a patch to the quilt series and tries to push it. - -patch-amend|pa --------------- -Open the top most patch in the editor directly to e.g. amend the -commit message. - -list-unused-patches [*--purge*] -------------------------------- -Lists unused patches and if --purge is specified deletes them. -Since the quilt patch pile is managed with git itself nothing -should get lost. - -baseline --------- -Prints out the current baseline sha1. - -git|g [*args*] --------------- -Run git with the given arguments in the quilt patches directory. - -gitk|k [*args*] ---------------- -Run gitk with the given argumenst in the quilt patches -directory. - -help ----- -This help text here - -all other subcommands - IMPORTANT ---------------------------------- -Any other subcommands are executed directly in the quilt patches -directory as git commans. When using quilt flow in scripts it is -import to use the explicit forwarding to avoid clashes with -furture extensions. - -CONTRIBUTING -============ - -Submit patches for any of the maintainer tools to -intel-gfx@xxxxxxxxxxxxxxxxxxxxx with [maintainer-tools PATCH] prefix. Use - -$ git format-patch --subject-prefix="maintainer-tools PATCH" - -for that. Push them once you have -an ack from maintainers (Jani/Daniel). -HERE + qf_help ;; *) cd_toplevel diff --git a/qf.rst b/qf.rst new file mode 100644 index 000000000000..5e13a2ae56e2 --- /dev/null +++ b/qf.rst @@ -0,0 +1,250 @@ +==== + qf +==== + +--------------------- +quilt git flow script +--------------------- + +:Author: Daniel Vetter <daniel.vetter@xxxxxxxx> +:Date: 2014-05-15 +:Copyright: 2013-2014 Intel Corporation +:Manual section: 1 +:Manual group: maintainer tools + +SYNOPSIS +======== + +**qf** *command* [*arg* ...] + +DESCRIPTION +=========== + +**qf** is a workflow script to manage a quilt patch pile on top of a +git baseline and track any changes in git itself. The quilt +patches and any other metadata is tracked in git refs outside of +the normal tag/branch namespace. The current baseline (as a git +commit sha1) of the quilt patch pile is also tracked. An +integral part is support to export the quilt patch to an git +branch in the baseline repository and push/fetch changes to the +remote linked to this branch. + +Assuming there's already a branch "test" set up to track a +remote a quickstart overview (output omitted): + +Getting started +--------------- +$ qf setup test + +$ qf checkout test + +This automatically either creates a new, empty patch pile or +checks out the state of an existing remote. + +Note that this only initializes the quilt side of things and +presumes that the test branch is set up already, including +remote tracking connection. To create a completely new branch +hence first run + +$ git checkout -b test --track origin/test + +Committing changes and publishing the resulting git tree +-------------------------------------------------------- +$ qf git gui # commit any changes in the patch directory + +$ qf export && qf push + +Rebasing +-------- +$ qf baseline # print old baseline commit + +$ qf rebase upstream + +$ qf baseline # check new baseline commit + +Following changes in upstream +----------------------------- +$ qf fetch + +$ qf git pull && qf checkout test + +Doing only a git pull on the quilt branch leads to an +inconsitent state if the baseline changed. + +Bisecting patch history +----------------------- + +Git history in the patches directory records every rebase or any other changes +to the patch pile, including the baseline. Which means it can be used for +bisecting not just the individual patches, but the history of the entire patch +pile: + +$ qf git bisect *old-sha1* *new-sha1* + +to start the bisect process, and then for each bisect step: + +$ qf checkout HEAD + +Run tests to figure out whether it's part of the new (bad) or old (good) +history, then tell git using + +$ qf git bisect new|old + +COMMANDS +======== + +setup [*branch-name*] +--------------------- +Sets up a git repository for this quilt worflow script by +creating and initializing (if this isn't done yet) the git +repository in <git-root>/patches. + +If a branch name is given it must exist in the baseline +repository. If so a quilt branch of the same name with +$QUILT_PREFIX is created and initialized (but without any +patches). The remote configuration is copied over from the +branch in the baseline repository. The script will fall over if +the branch in the baseline repository doesn't have a remote +properly set up. + +If the quilt branch already exists in the remote the quilt then +it is initialized with the latest state (which is updated with +git fetch beforehand). The remote quilt branch must have the +same name as the branch in the local baseline repository, the +script doesn't support disparate tracking names for the quilt +branch. + +Before the newly created branch can be used it needs to be +checked out first. + +checkout|co *commit-ish|quilt-branch* +------------------------------------- +Checks out the given branch/commit-ish (same rules as for git +checkout apply) in the patches directory. If you want to check +out an earlier revision you might need to run qf fetch first to +make sure that the base repo has all the baseline refs. When +checking out a branch it's not necessary to add the +$QUILT_PREFIX (quilt/ by default) to the branch name, the script +will complete the name automatically. + +At the end all quilt patches will be pushed. Presuming the quilt +flow state hasn't been hand-edited or an incompletely pushed +quilt branch has been committed this will always succeed. + +rebase *commit-ish* +------------------- +Pops off all quilt patches, rebases the baseline to the given +commit and then reapplys all the quilt patches up to the same +patch as before. Then updates the BASELINE variable in +patches/config. + +clean-patches +------------- +Removes all unused patch files from the patches/ directory. + +refresh +------- +Refreshes all the quilt patches up to the currently applied +patch. Then it commits a wash-up commit with all the refreshed +patches. The command aborts if there are uncommited changes in +the patches repository. + +export +------ +Flattens the current quilt branch and exports it into the +respective git branch in the base tree. + +The reflog'ed QUILT_EXPORT is always updated with the result of +the export. This is useful to export when in the detached HEAD +state in the quilt repository hence there's no branch to export +to. + +export-visualize|ev +------------------- +Visualizes the latest export result using gitk, down to the +current baseline. + +push +---- +Exports the tree and then pushes both the quilt branch, the +exported branch and any new baselines to the respective remotes. + +fetch +----- +Fetches both the main and patches barnch remotes and pulls all +the baseline refs into the main repo. + +pull [--rebase] +--------------- + +First runs qf fetch and then updates the patches branch (with a git merge) and +the checks out the latest working copy. When given --rebase will rebase the +patches branch instead of merging. + +stage +----- +Resets the git index and then (re-)applies all currently applied +quilt patches to it. Useful to use git tools like git diff to +compare changes against the quilt patch state. + +wiggle-push|wp +-------------- +Force-push the next patch and then wiggle in any conflicts. Does +not refresh the patch automatically, so that the conflict +resolution can be cross-checked. + +resolved +-------- +Little helper when a patch conflict was resolved. First +refreshes the topmost patch, then fires up vim to edit the +headers. + +apply *patch-name* +------------------ +Adds a patch to the quilt series and tries to push it. + +patch-amend|pa +-------------- +Open the top most patch in the editor directly to e.g. amend the +commit message. + +list-unused-patches [*--purge*] +------------------------------- +Lists unused patches and if --purge is specified deletes them. +Since the quilt patch pile is managed with git itself nothing +should get lost. + +baseline +-------- +Prints out the current baseline sha1. + +git|g [*args*] +-------------- +Run git with the given arguments in the quilt patches directory. + +gitk|k [*args*] +--------------- +Run gitk with the given argumenst in the quilt patches +directory. + +help +---- +This help text here + +all other subcommands - IMPORTANT +--------------------------------- +Any other subcommands are executed directly in the quilt patches +directory as git commans. When using quilt flow in scripts it is +import to use the explicit forwarding to avoid clashes with +furture extensions. + +CONTRIBUTING +============ + +Submit patches for any of the maintainer tools to +intel-gfx@xxxxxxxxxxxxxxxxxxxxx with [maintainer-tools PATCH] prefix. Use + +$ git format-patch --subject-prefix="maintainer-tools PATCH" + +for that. Push them once you have +an ack from maintainers (Jani/Daniel). -- 2.13.2 _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/intel-gfx