qf.rst 8.42 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
====
 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

.. Please use 'make mancheck' to validate updates to this file.

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
========

98 99 100 101 102 103 104 105 106 107
list-aliases
------------
List all aliases for the subcommand names.

See \$qf_alias_<alias> under ENVIRONMENT below on how to define aliases.

list-commands
-------------
List all subcommand names, including aliases.

108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
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
-------------
155 156
Removes all unused patch files from the patches/ directory. This
is the same as calling "qf list-unused-patches --purge".
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189

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.

190 191
pull
----
192

193 194 195
First runs qf fetch, then updates the patches branch, and
then checks out the latest working copy.
If fails if the patches branch can't be fast forwarded.
196 197 198 199 200 201 202

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.

203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
conflict-files
--------------
List the files that are probably in a unresolved stage of conflict.
Wiggle push will leave .rej and .porig files behind.
This is useful for manual conflict solving during the quilt rebase.

continue
--------
Clean up after wiggle and continue with quilt push -a to continue
applying and rebasing all the following patches.

wiggle-clean
------------
Clean up all .rej and .porig files that wiggle probably
left behind.

219 220 221 222 223 224 225 226 227
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
Rodrigo Vivi's avatar
Rodrigo Vivi committed
228
refreshes the topmost patch, then fires up $EDITOR to edit the
229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262
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

263 264 265 266
usage
-----
Short form usage help listing all subcommands.

267 268 269
all other subcommands - IMPORTANT
---------------------------------
Any other subcommands are executed directly in the quilt patches
270
directory as git commands. When using quilt flow in scripts it is
271 272 273
import to use the explicit forwarding to avoid clashes with
furture extensions.

Rodrigo Vivi's avatar
Rodrigo Vivi committed
274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298

ALIASES
=======

Extending **qf** functionalities
---------------------------------

It is possible to create your own qf helper and aliases by adding them to \$HOME/.qfrc::

	qf_my_fancy_list_aliases()
	{
		echo "Hello world!"
		qf_list_aliases
	}

	qf_alias_list_aliases=my-fancy-list-aliases

ENVIRONMENT
===========

QUILT_PREFIX
------------
Quilt branch prefix. This is a prefix for the git branch that contains the
patch files and quilt series file.

299 300
CONTRIBUTING, BUG REPORTS AND DISCUSSION
========================================
301

302 303
Submit patches, bug reports, and questions for any of the maintainer tools and
documentation to the dim-tools@lists.freedesktop.org mailing list.
304

305
Please make sure your patches pass the build and self tests by running::
306

307 308 309
  $ make check

Push the patches once you have an ack from maintainers (Jani/Daniel).