On Fri, 18 Aug 2017, Rodrigo Vivi <rodrigo.vivi@xxxxxxxxx> wrote: > No modification to the original content. Thanks, pushed with two additions: - added qf.rst to mancheck - added comment about mancheck in qf.rst BR, Jani. > > 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). -- Jani Nikula, Intel Open Source Technology Center _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/intel-gfx