[maintainer-tools PATCH] qf: Include qf man into sphinx docs.

[maintainer-tools PATCH] qf: Include qf man into sphinx docs.

[Rodrigo Vivi]

No modification to the original content.

Cc: Jani Nikula <jani.nikula@intel.com>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
---
 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@ffwll.ch>
-: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@lists.freedesktop.org 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@ffwll.ch>
+: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@lists.freedesktop.org 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@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [maintainer-tools PATCH] qf: Include qf man into sphinx docs.

[Jani Nikula]

On Fri, 18 Aug 2017, Rodrigo Vivi <rodrigo.vivi@intel.com> 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@intel.com>
> Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
> Signed-off-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
> ---
>  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@ffwll.ch>
> -: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@lists.freedesktop.org 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@ffwll.ch>
> +: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@lists.freedesktop.org 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@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx