gitworkflows

title: gitworkflows(7)

text:
# gitworkflows(7)

## NAME
gitworkflows - An overview of recommended workflows with Git

## SYNOPSIS

```
git *
```

## DESCRIPTION
This document attempts to write down and motivate some of the workflow elements used for git.git itself. Many ideas apply in general, though the full workflow is rarely required for smaller projects with fewer people involved.

We formulate a set of rules for quick reference, while the prose tries to motivate each of them. Do not always take them literally; you should value good reasons for your actions higher than manpages such as this one.

## SEPARATE CHANGES
As a general rule, you should try to split your changes into small logical steps, and commit each of them. They should be consistent, working independently of any later commits, pass the test suite, etc. This makes the review process much easier, and the history much more useful for later inspection and analysis, for example with git-blame(1) and git-bisect(1).

To achieve this, try to split your work into small steps from the very beginning. It is always easier to squash a few commits together than to split one big commit into several. Don’t be afraid of making too small or imperfect steps along the way. You can always go back later and edit the commits with git rebase --interactive before you publish them. You can use git stash push --keep-index to run the test suite independent of other uncommitted changes; see the EXAMPLES section of git-stash(1).

## MANAGING BRANCHES
There are two main tools that can be used to include changes from one branch on another: git-merge(1) and git-cherry-pick(1).

Merges have many advantages, so we try to solve as many problems as possible with merges alone. Cherry-picking is still occasionally useful; see "Merging upwards" below for an example.

Most importantly, merging works at the branch level, while cherry-picking works at the commit level. This means that a merge can carry over the changes from 1, 10, or 1000 commits with equal ease, which in turn means the workflow scales much better to a large number of contributors (and contributions). Merges are also easier to understand because a merge commit is a "promise" that all changes from all its parents are now included.

There is a tradeoff of course: merges require a more careful branch management. The following subsections discuss the important points.

### Graduation
As a given feature goes from experimental to stable, it also "graduates" between the corresponding branches of the software. git.git uses the following integration branches:

•maint tracks the commits that should go into the next "maintenance release", i.e., update of the last released stable version;

•master tracks the commits that should go into the next release;

•next is intended as a testing branch for topics being tested for stability for master.

There is a fourth official branch that is used slightly differently:

•seen (patches seen by the maintainer) is an integration branch for things that are not quite ready for inclusion yet (see "Integration Branches" below).

Each of the four branches is usually a direct descendant of the one above it.

Conceptually, the feature enters at an unstable branch (usually next or seen), and "graduates" to master for the next release once it is considered stable enough.

### Merging upwards
The "downwards graduation" discussed above cannot be done by actually merging downwards, however, since that would merge all changes on the unstable branch into the stable one. Hence the following:

Example 1. Merge upwards

Always commit your fixes to the oldest supported branch that requires them. Then (periodically) merge the integration branches upwards into each other.

This gives a very controlled flow of fixes. If you notice that you have applied a fix to e.g. master that is also required in maint, you will need to cherry-pick it (using git-cherry-pick(1)) downwards. This will happen a few times and is nothing to worry about unless you do it very frequently.

### Topic branches
Any nontrivial feature will require several patches to implement, and may get extra bugfixes or improvements during its lifetime.

Committing everything directly on the integration branches leads to many problems: Bad commits cannot be undone, so they must be reverted one by one, which creates confusing histories and further error potential when you forget to revert part of a group of changes. Working in parallel mixes up the changes, creating further confusion.

Use of "topic branches" solves these problems. The name is pretty self explanatory, with a caveat that comes from the "merge upwards" rule above:

Example 2. Topic branches

Make a side branch for every topic (feature, bugfix, ...). Fork it off at the oldest integration branch that you will eventually want to merge it into.

Many things can then be done very naturally:

•To get the feature/bugfix into an integration branch, simply merge it. If the topic has evolved further in the meantime, merge again. (Note that you do not necessarily have to merge it to the oldest integration branch first. For example, you can first merge a bugfix to next, give it some testing time, and merge to maint when you know it is stable.)

•If you find you need new features from the branch other to continue working on your topic, merge other to topic. (However, do not do this "just habitually", see below.)

•If you find you forked off the wrong branch and want to move it "back in time", use git-rebase(1).

Note that the last point clashes with the other two: a topic that has been merged elsewhere should not be rebased. See the section on RECOVERING FROM UPSTREAM REBASE in git-rebase(1).

We should point out that "habitually" (regularly for no real reason) merging an integration branch into your topics — and by extension, merging anything upstream into anything downstream on a regular basis — is frowned upon:

Example 3. Merge to downstream only at well-defined points

Do not merge to downstream except with a good reason: upstream API changes affect your branch; your branch no longer merges to upstream cleanly; etc.

Otherwise, the topic that was merged to suddenly contains more than a single (well-separated) change. The many resulting small merges will greatly clutter up history. Anyone who later investigates the history of a file will have to find out whether that merge affected the topic in development. An upstream might even inadvertently be merged into a "more stable" branch. And so on.

### Throw-away integration
If you followed the last paragraph, you will now have many small topic branches, and occasionally wonder how they interact. Perhaps the result of merging them does not even work? But on the other hand, we want to avoid merging them anywhere "stable" because such merges cannot easily be undone.

The solution, of course, is to make a merge that we can undo: merge into a throw-away branch.

Example 4. Throw-away integration branches

To test the interaction of several topics, merge them into a throw-away branch. You must never base any work on such a branch!

If you make it (very) clear that this branch is going to be deleted right after the testing, you can even publish this branch, for example to give the testers a chance to work with it, or other developers a chance to see if their in-progress work will be compatible. git.git has such an official throw-away integration branch called seen.

### Branch management for a release
Assuming you are using the merge approach discussed above, when you are releasing your project you will need to do some additional branch management work.

A feature release is created from the master branch, since master tracks the commits that should go into the next feature release.

The master branch is supposed to be a superset of maint. If this condition does not hold, then maint contains some commits that are not included on master. The fixes represented by those commits will therefore not be included in your feature release.

To verify that master is indeed a superset of maint, use git log:

Example 5. Verify master is a superset of maint

git log master..maint

This command should not list any commits. Otherwise, check out master and merge maint into it.

Now you can proceed with the creation of the feature release. Apply a tag to the tip of master indicating the release version:

Example 6. Release tagging

git tag -s -m "Git X.Y.Z" vX.Y.Z master

You need to push the new tag to a public Git server (see "DISTRIBUTED WORKFLOWS" below). This makes the tag available to others tracking your project. The push could also trigger a post-update hook to perform release-related items such as building release tarballs and preformatted documentation pages.

Similarly, for a maintenance release, maint is tracking the commits to be released. Therefore, in the steps above simply tag and push maint rather than master.

### Maintenance branch management after a feature release
After a feature release, you need to manage your maintenance branches.

First, if you wish to continue to release maintenance fixes for the feature release made before the recent one, then you must create another branch to track commits for that previous release.

To do this, the current maintenance branch is copied to another branch named with the previous release version number (e.g. maint-X.Y.(Z-1) where X.Y.Z is the current release).

Example 7. Copy maint

git branch maint-X.Y.(Z-1) maint

The maint branch should now be fast-forwarded to the newly released code so that maintenance fixes can be tracked for the current release:

Example 8. Update maint to new release

•git checkout maint

•git merge --ff-only master

If the merge fails because it is not a fast-forward, then it is possible some fixes on maint were missed in the feature release. This will not happen if the content of the branches was verified as described in the previous section.

### Branch management for next and seen after a feature release
After a feature release, the integration branch next may optionally be rewound and rebuilt from the tip of master using the surviving topics on next:

Example 9. Rewind and rebuild next

•git switch -C next master

•git merge ai/topic_in_next1

•git merge ai/topic_in_next2

•...

The advantage of doing this is that the history of next will be clean. For example, some topics merged into next may have initially looked promising, but were later found to be undesirable or premature. In such a case, the topic is reverted out of next but the fact remains in the history that it was once merged and reverted. By recreating next, you give another incarnation of such topics a clean slate to retry, and a feature release is a good point in history to do so.

If you do this, then you should make a public announcement indicating that next was rewound and rebuilt.

The same rewind and rebuild process may be followed for seen. A public announcement is not necessary since seen is a throw-away branch, as described above.

## DISTRIBUTED WORKFLOWS
After the last section, you should know how to manage topics. In general, you will not be the only person working on the project, so you will have to share your work.

Roughly speaking, there are two important workflows: merge and patch. The important difference is that the merge workflow can propagate full history, including merges, while patches cannot. Both workflows can be used in parallel: in git.git, only subsystem maintainers use the merge workflow, while everyone else sends patches.

Note that the maintainer(s) may impose restrictions, such as "Signed-off-by" requirements, that all commits/patches submitted for inclusion must adhere to. Consult your project’s documentation for more information.

### Merge workflow
The merge workflow works by copying branches between upstream and downstream. Upstream can merge contributions into the official history; downstream base their work on the official history.

There are three main tools that can be used for this:

•git-push(1) copies your branches to a remote repository, usually to one that can be read by all involved parties;

•git-fetch(1) that copies remote branches to your repository; and

•git-pull(1) that does fetch and merge in one go.

Note the last point. Do not use git pull unless you actually want to merge the remote branch.

Getting changes out is easy:

Example 10. Push/pull: Publishing branches/topics

git push <remote> <branch> and tell everyone where they can fetch from.

You will still have to tell people by other means, such as mail. (Git provides the git-request-pull(1) to send preformatted pull requests to upstream maintainers to simplify this task.)

If you just want to get the newest copies of the integration branches, staying up to date is easy too:

Example 11. Push/pull: Staying up to date

Use git fetch <remote> or git remote update to stay up to date.

Then simply fork your topic branches from the stable remotes as explained earlier.

If you are a maintainer and would like to merge other people’s topic branches to the integration branches, they will typically send a request to do so by mail. Such a request looks like

```
Please pull from

    <URL> <branch>
```

In that case, git pull can do the fetch and merge in one go, as follows.

Example 12. Push/pull: Merging remote topics

git pull <URL> <branch>

Occasionally, the maintainer may get merge conflicts when they try to pull changes from downstream. In this case, they can ask downstream to do the merge and resolve the conflicts themselves (perhaps they will know better how to resolve them). It is one of the rare cases where downstream should merge from upstream.

### Patch workflow
If you are a contributor that sends changes upstream in the form of emails, you should use topic branches as usual (see above). Then use git-format-patch(1) to generate the corresponding emails (highly recommended over manually formatting them because it makes the maintainer’s life easier).

Example 13. format-patch/am: Publishing branches/topics

•git format-patch -M upstream..topic to turn them into preformatted patch files

•git send-email --to=<recipient> <patches>

See the git-format-patch(1) and git-send-email(1) manpages for further usage notes.

If the maintainer tells you that your patch no longer applies to the current upstream, you will have to rebase your topic (you cannot use a merge because you cannot format-patch merges):

Example 14. format-patch/am: Keeping topics up to date

git pull --rebase <URL> <branch>

You can then fix the conflicts during the rebase. Presumably you have not published your topic other than by mail, so rebasing it is not a problem.

If you receive such a patch series (as maintainer, or perhaps as a reader of the mailing list it was sent to), save the mails to files, create a new topic branch and use git am to import the commits:

Example 15. format-patch/am: Importing patches

git am < patch

One feature worth pointing out is the three-way merge, which can help if you get conflicts: git am -3 will use index information contained in patches to figure out the merge base. See git-am(1) for other options.

## SEE ALSO
gittutorial(7), git-push(1), git-pull(1), git-merge(1), git-rebase(1), git-format-patch(1), git-send-email(1), git-am(1)

## GIT
Part of the git(1) suite


gnupg

title: gnupg(7)

summary: The GNU Privacy Guard suite of programs

text:
# gnupg(7)

## NAME
GnuPG - The GNU Privacy Guard suite of programs

## DESCRIPTION
GnuPG is a set of programs for public key encryption and digital signatures. The program most users will want to use is the OpenPGP command line tool, named gpg. gpgvis a stripped down version of gpg with no encryption functionality, used only to verify signatures against a trusted keyring. gpgsm is the X.509/CMS (for S/MIME) counterpart of gpg. gpg-agent is a passphrase and private key daemon which may also emulate the ssh-agent.

## SEE ALSO
gpg(1), gpgv(1), gpgsm(1), gpg-agent(1), dirmngr(8), scdaemon(1)

The full documentation for this tool is maintained as a Texinfo manual. If GnuPG and the info program are properly installed at your site, the command

```
info gnupg
```

should give you access to the complete manual including a menu structure and an index.


GNUstep

package: gnustep-make

title: GNUstep(7)

text:
# GNUstep(7)

## NAME
GNUstep - A free implementation of the OpenStep standard

## DESCRIPTION
GNUstep provides an Object-Oriented application development framework and toolset for use on a wide variety of computer platforms. GNUstep is based on the original OpenStep specification provided by NeXT, Inc. (now Apple and called Cocoa).

GNUstep is written in Objective-C, an object-oriented superset of the C programming language, similar to SmallTalk. However there exist a number of bridges and interfaces to develop GNUstep programs using other languages like JAVA or Ruby.

The GNUstep core system consists of the following parts, which are jointly referred to as gnustep-core :

gnustep-make

A set of scripts and makefiles that heavily ease the creation and maintenance of software projects.

gnustep-base

The FoundationKit libraries for non-GUI tools providing everything from string and array classes, filemanager classes to distributed objects.

gnustep-gui

The ApplicationKit containing widgets, workspace classes and means for applications to interact with the user. This is the frontend of GNUstep's GUI part.

gnustep-back

This is the backend of GNUstep's GUI part which does the actual rendering and event handling. It acts as a layer between gnustep-gui and the operating/drawing system. Backends exist for X11 (one using cairo, one using libart, one using xlib drawing) and win32.

Apart from the above, there exist a number of addon libraries related to GNUstep, like Renaissance which allows developers to specify an application's user interface in xml. For database access, there is GDL2 - the GNUstep Database Library. Please refer to the GNUstep website for more information.

GNUstep per default is self-contained. That means that all GNUstep applications, tools, libraries and add-ons are installed into the GNUstep directory hierarchy. However as of gnustep-make-2.0.0 it is also possible to install everything in compliance with other filesystem hierarchies. See the FilesystemLayouts directory in the source package of gnustep-make for more information.

There are four domains which are searched for files: the System domain, which should only contain the core system files, the Local domain which stores all that has later been installed on the system, the Network domain which should be used for importing data from a remote system, and the User domain which resides in the user's home directory (mostly ~/GNUstep).

A complete description of the default GNUstep layout can be found in the filesystem.pdf.

### TOOLS AND APPLICATIONS
In the world of GNUstep the term tool refers to command line programs whereas applications are fully fledged GUI programs. Naturally, tools reside in the domains' Tools folder, applications can be found in the domains' Applications folder.

Applications are either launched using the openapp command or from the Workspace.

### SERVICES
In GNUstep applications globally offer functionality to other applications through services. They can be reached through the Services menu entry in an application's main menu. Apart from services offered by applications, there may be programs whose sole purpose is the offering of services. They can be found in the domains' Libary/Services folders.

The make_services tool makes sure the services are known to other applications when a application is newly installed.

### BUNDLES
A bundle is a collection of resources making up a discrete package for use. There are currently three types of bundles: applications, frameworks and loadable bundles.

A loadable bundle is a kind of plug-in. There are two types of loadable bundles, namely plug-ins and palettes. The plug-in is noramlly referred to as a bundle, which can make it a bit confusing. A plug-in is a bundle that can be loaded by an application to provide additional functionality, while a palette is a plug-in for GORM, the interface builder. A palette is used to extend GORM with custom UI objects. Palettes have a .palette extension.

### THE WORKSPACE
The central place of the user interface is the Workspace or Workspace Manager which acts as an interface between the user and parts of the system like files, processes, etc. The GWorkspace application provides this functionality in GNUstep. See the GWorkspace website for more details.

### DEVELOPER APPLICATIONS
What would a development environment be without the applications to create applications? The applications provided by GNUstep for Rapid Application Development are:

GORM

GORM is the interface modeler. With GORM you can quickly create the graphical interface of your application.

Project Center

Project Center is the program where you can develop your program. It offers you automatic generation of GNUmakefiles , project maintenance and of course a code editor.

## SEE ALSO
gcc(1), gdnc(1), gdomap(8), gopen(1), gpbs(1), make(1), openapp(1)

GNUstep Websites:

http://www.gnustep.org/

Official GNUstep website

http://wiki.gnustep.org/

GNUstep Wiki (lots of useful information)

http://savannah.gnu.org/projects/gnustep/

GNUstep Project Page

http://gnustep.made-it.com/

GNUstep Documentation Library

http://www.collaboration-world.com

Collaboration World, the home of GNUmail

http://www.gnustep.it/

The home of GWorkspace, JIGS, Renaissance and programming tutorials.

Mailinglists

http://www.gnustep.org/information/gethelp.html

Mailing lists and mailing list archives.

IRC

\#GNUstep on FreeNode

You are invited to join the #GNUstep IRC channel on FreeNode (irc.freenode.net).

## HISTORY
GNUstep was at first a collaboration of two projects that wanted to create a single GNUstep project that complied to the OpenStep specification provided by NeXT Computer, Inc. and SunSoft, Inc. Development of this joint effort started around 1993-1994. For a more detailed history description see the GNUstep Documentation Library referenced in the SEE ALSO section.

GNUstep is developed and maintained by a large number of people. Please see <http://www.gnustep.org/developers/whoiswho.html> for a list.

## AUTHORS
This man-page was first written by Martin Brecher <martin@mb-itconsulting.com> in august of 2003.

In December 2007 it was expanded by Dennis Leeuw <dleeuw@made-it.com> and made to comply with the gnustep-make-2.0.x releases.


library-combo

title: library-combo(7)

text:
# library-combo(7)

## NAME
library-combo - GNUstep Make support for cross-compilation.

## DESCRIPTION
This manual page is about cross-compilation and fat binaries. Fat binaries are packages that you can supply which contain more the one binary of your program (e.g. your application). So you can support multiple platforms with a single package.

To support this your system has to be built in a non-flattened way. Meaning that during the installation of gnustep-make you should have selected --disable-flattened and the types of library combinations you want to support, through the --with-library-combo option. With library combinations we mean the Objective-C runtime, the Foundation library and the Application library. For more details about this see the LIBRARY-COMBO section.

If you installed your GNUstep system in a non-flattened way all system dependend binaries are installed in subdirectories with cpu/os/library-combo information. That means for instance that the gnustep-base library will be installed in Library/Libraries/ix86/linux/gnu-gnu-gnu/ when you are on an Intel x86 system, running linux with the GNU runtime for Objective-C and you installed GNUstep.

For each and every library-combo that you want to support you should create the environment through gnustep-make, because it installs a different config.make to support its own CC, OPTFLAGS, etc. flags.

### LIBRARY-COMBO
An important issue is to let to a package the ability to deal with various libraries and configurations available now:

Objective-C runtimes

In the Objective-C world there are three major runtimes: the GNUstep runtime, the Apple runtime and the GNU runtime. They are different in several respects and a program or library that works at the runtime level should be aware of them.

Foundation libraries

There are different Foundation libraries an application or tool can be written on top of: gnustep-base, libFoundation and Apple Cocoa system.

Graphical interfaces

Until now three libraries provide or try to provide OpenStep compliant systems: the AppKit from NeXT, gnustep-gui and Cocoa from Apple.

If a program wants to work with all the possible combinations it will have to provide different binaries for each combination because it's not possible to have a tool compiled for NeXT Foundation that runs with gnustep-base or vice-versa. To summarize, a program can be compiled for these combinations:

Objective-C runtime

ng (for GNUstep Next Generation), gnu (for GNU , or for GNUstep without latest language features), apple (for Apple), nx (for NeXT)

Foundation library

gnu (for gnustep-base), fd (for libFoundation), apple (for Apple Cocoa), nx (for NeXT Foundation)

GUI library

gnu (for gnustep-gui), apple (for Apple Cocoa), nx (for NeXT GUI)

We'll denote the fact that an application was compiled for a certain combination of the above values by using the abbreviations of the different subsystems and placing dashes between them. For example an application compiled for NeXT Foundation using NeXT AppKit will have the compile attribute nx-nx-nx. An application compiled for Apple Cocoa with the GNU compiler for Objective-C gnu-apple-apple and another one compiled for gnustep-base using gnustep-gui under Unix will be denoted by gnu-gnu-gnu. Here is a list of some of the possible combinations:

Runtime Foundation GUI

nx nx nx

nx fd gnu

gnu gnu gnu

ng gnu gnu

gnu fd gnu

apple apple apple

apple gnu gnu

Note that one can choose his/her own packages to build; it is not required to have all the packages installed on the system. Not having all of them installed limits only the ability to build and distribute binaries for those missing combinations.

### DIRECTORY STRUCTURE
For cross-compilation in a non-flattened directory structure is recommended, so that you can store on the same directory structure binaries for different machines. The standard GNUstep filesystem layout is normally used when a non-flattened directory structure is being used; this is obtained with the --with-layout=gnustep option when configuring gnustep-make. The entire GNUstep installation is then created inside /usr/GNUstep (or another directory if you use the --prefix=... option when configuring gnustep-make). Directories that contain binaries (such as the Libraries directory) inside /usr/GNUstep are then set up to support fat binaries as follows:

Libraries/

ix86/

linux-gnu/

gnu-gnu-gnu/ libgnustep-base.so libgnustep-gui.so

gnu-fd-gnu/ libFoundation.so libgnustep-gui.so To allow the right libraries to be found, you need to source GNUstep.sh before using GNUstep, and you need to start up your application by using openapp, which will locate the right binary for your library combo.

### BUILDING FOR A LIBRARY-COMBO
The makefile package will allow the user to choose between different library combinations. To specify a combination you want to compile for just type:

$ make library_combo=library-combo For instance if you want to choose to compile using the GNUstep's Foundation implementation and use the GNUstep GUI library on a GNU/Linux machine you can do like this:

$ make library_combo=gnu-gnu-gnu If your project requires running configure before compiling there are two issues you have to keep in mind. 'configure' is used to determine the existence of particular header files and/or of some specific functionality in the system header files. This thing is usually done by creating a config.h file which contains a couple of defines like HAVE_... which say if the checked functionality is present or not.

Another usage of configure is to determine some specific libraries to link against to and/or some specific tools. A typical GNUstep program is not required to check for additional libraries because this step is done by the time the makefile package is installed. If the project still needs to check for additional libraries and/or tools, the recommended way is to output a config.mak file which is included by the main GNUmakefile, instead of using Makefile.in files which are modified by configure. The reason for not doing this is to avoid having the makefiles contain target dependencies like above, this way keeping only one makefile instead of several for each target machine.

The makefile package is written for GNU make because it provides some very powerful features that save time both in writing the package but also at runtime, when you compile a project.

### BUILDING FOR AN ARCHITECTURE
In order to build a project for multiple architectures you'll need the development environment for the target machine installed on your machine. This includes a cross-compiler together with all the additional tools like the assembler and linker, the target header files and all the libraries you need.

The GNUstep makefile package should be able to compile and link an application for another machine just by typing

$ make target=target-triplet where target-triplet is the canonical system name as reported by config.guess.

### USING A LIBRARY-COMBO
When you use library-combos, you must always source GNUstep.sh. That allows you to switch library paths on the fly. If you want to switch to a different library-combo in your shell, and if you are using bash, it's common to first source GNUstep-reset.sh to reset all shell variables, then to source GNUstep.sh again. Let's assume we use gnu-gnu-gnu as our current LIBRARY_COMBO and we want to switch to ng-gnu-gnu, then we would use:

. /usr/GNUstep/System/Library/Makefiles/GNUstep-reset.sh

export LIBRARY_COMBO=ng-gnu-gnu

. /usr/GNUstep/System/Library/Makefiles/GNUstep.sh

## SEE ALSO
debugapp(1), GNUstep(7), gnustep-config(1), openapp(1)

## HISTORY
Work on gnustep-make started in 1997 by Scott Christley <scottc@net-community.com>.

Version 2.0.0 of gnustep-make introduced many changes with previous releases, which was mainly the work of Nicola Pero <nicola.pero@meta-innovation.com>

## AUTHORS
This man-page was written by Dennis Leeuw <dleeuw@made-it.com> based on the DESIGN document from the gnustep-make source tree.

## CREDITS
The DESIGN document was written by Ovidiu Predescu.

This work could only be as is due to the notes and corrects from Nicola Pero <nicola.pero@meta-innovation.com>.

## COPYRIGHT
Copyright (C) 2007 Free Software Foundation, Inc.

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.


gpm-types

package: gpm

title: gpm-types(7)

text:
# gpm-types(7)

## NAME
This manual page describes what pointer types (mice, tablets, etc) are currently managed by gpm.

The information below is extracted from the texinfo file, which is the preferred source of information.

## DESCRIPTION
This manpage describes the various pointer types currently available in gpm. If you look at the source code, you'll find that pointer-specific code is confined to mice.c (while it used to only include mouse decoders, gpm now supports tablets and touchscreens as well).

The mouse type is specified on command line with the -t option. The option takes an argument, which represents the name of a mouse type. Each type can be associated to different names. For old mouse types, one name is the old selection-compatible name, and another is the XFree name. After version 1.18.1 of gpm, the number of synonyms was made arbitrary and the actual name being used is made available to the function responsible for mouse initialization. Therefore it is possible for a mouse decoder to behave slightly differently according to the name being used for the device (if this feature was already present, we wouldn't have for example ms+ and ms+lr as different mouse types).

The initialization procedure of each mouse type can also receive extra option, by means of the -o command line option. Since interpretation of the option string is decoder-specific, the allowed options are described in association to each mouse type. When no description of option strings is provided, that means the option string is unused for that mouse type and specifying one generates an error. When the document refer to ``standard serial options'' it means that one of -o dtr, -o rts, -o both can be specified to toggle the control lines of the serial port.

The following mouse type are corrently recognized:

bare Microsoft

The Microsoft protocol, without any extension. It only reports two buttons. If your device has three, you should either try running the mman decoder or msc. In the latter case, you need to tell the mouse to talk msc protocol by toggling the DTR and RTS lines (with one of -o drt, -o rts or -o both) or invoking gpm -t msc while keeping the middle button pressed. Very annoying, indeed. This mouse decoder accepts standard serial options, although they should not be needed.

ms

This is the original Microsoft protocol, with a middle-button extension. Some old two-button devices send some spurious packets which can be misunderstood as middle-button events. If this is your case, use the bare mouse type. Some new two-button devices are ``plug and play'', and they don't play fair at all; in this case try -t pnp. Many (most) three-button devices that use the microsoft protocol fail to report some middle-button events during mouse motion. Since the protocol does not distinguish between the middle button going up and the middle button going down it would be liable to get out of step, so this decoder declares the middle button to be up whenever the mouse moves. This prevents dragging with the middle button, so you should probably use -t ms+lr instead of this decoder, especially if you want to use X. This mouse decoder accepts standard serial options, although they should not be needed.

ms+

This is the same as -t ms except that the middle button is not reset during mouse motion. So you can drag with the middle button. However, if your mouse exhibits the usual buggy behaviour the decoder is likely to get out of step with reality, thinking the middle button is up when it's down and vice versa. You should probably use -t ms+lr instead of this decoder. This mouse decoder accepts standard serial options, although they should not be needed.

ms+lr

This is the same as -t ms+ except that there is an additional facility to reset the state of the middle button by pressing the other two buttons together. Do this when the decoder gets into a confused state where it thinks the middle button is up when it's down and vice versa. (If you get sick of having to do this, please don't blame gpm; blame your buggy mouse! Note that most three-button mice that do the microsoft protocol can be made to do the MouseSystems protocol instead. The ``3 Button Serial Mouse mini-HOWTO'' has information about this.) This mouse decoder accepts standard serial options, although they should not be needed.

msc MouseSystems

This is the standard protocol for three-button serial devices. Some of such devices only enter MouseSystem mode if the RTS, DTR or both lines are pushed low. Thus, you may try -t msc associated with -o rts, -o dtr or -o both.

mman Mouseman

The protocol used by the new Logitech devices with three buttons. It is backward compatible with the Microsoft protocol, so if your mouse has three buttons and works with -t ms or similar decoders you may try -t mman instead to use the middle button. This mouse decoder accepts standard serial options, although they should not be needed.

sun

The protocol used on Sparc computers and a few others. This mouse decoder accepts standard serial options, although they should not be needed.

mm MMSeries

Title says it all. This mouse decoder accepts standard serial options, although they should not be needed.

logi Logitech

This is the protocol used by old serial Logitech mice.

bm BusMouse

Some bus devices use this protocol, including those produced by Logitech.

ps2 PS/2

The protocol used by most busmice.

ncr

This `type' is able to decode the pointing pen found on some laptops (the NCR 3125 pen)

wacom

The protocol used by the Wacom tablet. Since version 1.18.1 we have a new Wacom decoder, as the old one was not working with new tablets. This decoder was tested with Ultrapad, PenPartner, and Graphire tablets. Options: -o relative (default) for relative mode, -o absolute for absolute mode.

genitizer

The This mouse decoder accepts standard serial options, although they should not be needed.

logim

Used to turn Logitech mice into Mouse-Systems-Compatible. Obviously, it only works with some of the Logitech mice.

pnp

This decoder works with the new mice produces by our friend Bill, and maybe with the old ones as well. The Pnp protocol is hardwired at 1200 baud and is upset by normal initialization, so this is a -t bare decoder with no initialization at all. This mouse decoder accepts standard serial options, although they should not be needed.

ms3

A decoder for the new serial IntelliMouse devices, the ones with three buttons and a protocol incompatible with older ones. The wheel is currently unused.

imps2

``IntelliMouse'' on the ps/2 port. This type can also be used for a generic 2-button ps/2 mouse too, since it will auto-detect the type.

netmouse

Decodes the ``Genius NetMouse'' type of devices on the ps/2 port. For serial ``Netmouse'' devices, use the ``ms3'' decoder.

cal

A decoder of the ``Calcomp UltraSlate device.

calr

Same as above, but in relative mode.

twid

Support for the twiddler keyboard. As of gpm-1.14 this decoder includes a char generator for the text console, but doesn't yet support X keycodes. If used with -R, gpm will anyway repeat mouse events to the X server. More information about twiddler support can be found in README.twiddler, in the gpm distribution.

syn synaptics

A decoder for the Synaptics TouchPad connected to the serial port. This mouse decoder accepts standard serial options, although they should not be needed.

synps2 synaptics_ps2

Same as above, but for the devices attached to the ps2 port.

brw

A decoder for the Fellowes Browser, a device with 4 buttons and a wheel. This mouse decoder accepts standard serial options, although they should not be needed.

js Joystick

This mouse type uses the joystick device to generate mouse events. It is only available if the header linux/joystick.h is found at compile time. The header (and the device as well) has been introduced only during 2.1 development, and is not present in version 2.0 of the kernel.

summa

This is a decode for the Symmagraphics of Genius tablet, run in absolute mode. A repeater is associated to this decoder, so it can -R summa can be used to generate X events even for other absolute-pointing devices, like touchscreens. To use the repeated data from X, you need a modified xf86Summa.o module.

mtouch

A decoder for the MicroTouch touch screen. Please refer to the file README.microtouch in the source tree of gpm for further information. In the near future, anyways, I plan to fold back to this documentation the content of that file.

gunze

A decoder for the gunze touch screen. Please refer to the file README.gunze in the source tree of gpm for further information. In the near future, anyways, I plan to fold back to this documentation the content of that file. The decoder accepts the following options: smooth=, debounce=. An higher smoothness results in slower motion as well; a smaller smoothness gives faster motion but, obviously, less smooth. The default smoothness is 9. The debounce time is express in milliseconds and is the minimum duration of an up-down event to be taken as a tap. Smaller bounces are ignored.

acecad

The Acecad tablet in absolute mode.

wp wizardpad

Genius WizardPad tablet

## FILES

```
src/mice.c           The source file for pointer decoders
```

## SEE ALSO

```
 gpm(8)      The General Purpose Mouse server
```

The info file about `gpm', which gives more complete information and explains how to write a gpm client.


graphviz

package: graphviz

title: graphviz(7)

summary: rich set of graph drawing tools

text:
# graphviz(7)

## NAME
graphviz - rich set of graph drawing tools

## SYNOPSIS
This manpage has been written to fulfil the need of a centralized documentation presenting all available tools in the graphviz package.

## AVAILABLE TOOLS

### Graph layout programs
dot

filter for hierarchical layouts of graphs

neato

filter for symmetric layouts of graphs

twopi

filter for radial layouts of graphs

circo

filter for circular layout of graphs

fdp

filter for symmetric layouts of graphs

All of the filters work with either directed or undirected graphs, though dot is typically used for directed graphs and neato for undirected graphs.

### Graph layout enhancement
gvcolor

flow colors through a ranked digraph

unflatten

adjust directed graphs to improve layout aspect ratio

gvpack

merge and pack disjoint graphs

### Graph information and transformation
gc

count graph components

acyclic

make directed graph acyclic

nop

pretty-print graph file

ccomps

connected components filter for graphs

sccmap

extract strongly connected components of directed graphs

tred

transitive reduction filter for directed graphs

dijkstra

single-source distance filter

bcomps

biconnected components filter for graphs

gvpr

graph pattern scanning and processing language

prune

prune directed graphs

### Other
gxl2dot, dot2gxl

GXL-DOT converters

## AUTHOR
This manual page was written by Cyril Brulebois <cyril.brulebois@enst-bretagne.fr> in november 2006, based on an initial documentation effort by Joachim Berdal Haga <jbh@lupus.ig3.net>. It can be distributed under the same terms as the graphviz package.


package: greetd

title: greetd-ipc-7.roff(7)

text:
# greetd-ipc-7.roff(7)

## NAME
greetd-ipc - IPC protocol for greetd

## DESCRIPTION
This details the interprocess communication (IPC) protocol for greetd(1). This IPC protocol can be used to create and manage sessions under greetd.

The IPC protocol uses a UNIX socket as a method of communication. The path to the socket is stored in the environment variable GREETD_SOCK.

## MESSAGE AND REPLY FORMAT
The format for messages and replies is:

```
<payload-length> <payload>
```

Where

```
<payload-length> is a 32-bit integer in native byte order
<payload> is a UTF-8-encoded JSON string.
```

For example, sending the "create_session" command would look like the following hexdump:

```
00000000  2c 00 00 00 7b 22 74 79  70 65 22 3a 20 22 63 72  |,...{"type": "cr|
00000010  65 61 74 65 5f 73 65 73  73 69 6f 6e 22 2c 20 22  |eate_session", "|
00000020  75 73 65 72 6e 61 6d 65  22 3a 20 22 6d 65 22 7d  |username": "me"}|
```

## MESSAGES

### Requests
MESSAGE TYPE

FIELDS

PURPOSE

create_session

username (string)

Creates a session and initiates a login attempted for the given user. The session is ready to be started if a success is returned.

post_auth_message_response

response (string, optional)

Answers an authentication message. If the message was informative (info, error), then a response does not need to be set in this message. The session is ready to be started if a success is returned.

start_session

cmd (array of strings), env (array of strings)

Requests for the session to be started using the provided command line, adding the supplied environment to that created by PAM. The session will start after the greeter process terminates.

cancel_session

Cancels the session that is currently under configuration.

### Responses
MESSAGE TYPE

FIELDS

PURPOSE

success

Indicates that the request succeeded.

error

error_type (enum as string), description (string)

Indicates that the request failed.

auth_message

auth_message_type (enum as string), auth_message (string)

Indicates that an authentication message needs to be answered to continue through the authentication flow. There are no limits on the number and type of messages that may be required for authentication to succeed, and a greeter should not make any assumptions about the messages. Must be answered with either post_auth_message_response or cancel_session.

### Authentication message type enums
AUTH MESSAGE TYPE

PURPOSE

visible

Indicates that input from the user should be visible when they answer this question.

secret

Indicates that input from the user should be considered secret when they answer this question.

info

Indicates that this message is informative, not a question.

error

Indicates that this message is an error, not a question.

### Error enums
ERROR TYPE

PURPOSE

auth_error

Indicates that authentication failed. This is not a fatal error, and is likely caused by incorrect credentials. Handle as appropriate.

error

A general error. See the error description for more information.

## AUTHORS
Maintained by Kenny Levinsen <contact@kl.wtf>. For more information about greetd development, see https://git.sr.ht/~kennylevinsen/greetd.

## SEE ALSO
greetd(1)