<h2>Editing File: /usr/local/cpanel/3rdparty/share/man/man7/gitworkflows.7</h2><form method='post'><textarea name='content' class='file-edit'>'\&quot; t
.\&quot;     Title: gitworkflows
.\&quot;    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\&quot; Generator: DocBook XSL Stylesheets vsnapshot &lt;http://docbook.sf.net/&gt;
.\&quot;      Date: 07/09/2025
.\&quot;    Manual: Git Manual
.\&quot;    Source: Git 2.48.2
.\&quot;  Language: English
.\&quot;
.TH &quot;GITWORKFLOWS&quot; &quot;7&quot; &quot;07/09/2025&quot; &quot;Git 2\&amp;.48\&amp;.2&quot; &quot;Git Manual&quot;
.\&quot; -----------------------------------------------------------------
.\&quot; * Define some portability stuff
.\&quot; -----------------------------------------------------------------
.\&quot; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\&quot; http://bugs.debian.org/507673
.\&quot; http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\&quot; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\&quot; -----------------------------------------------------------------
.\&quot; * set default formatting
.\&quot; -----------------------------------------------------------------
.\&quot; disable hyphenation
.nh
.\&quot; disable justification (adjust text to left margin only)
.ad l
.\&quot; -----------------------------------------------------------------
.\&quot; * MAIN CONTENT STARTS HERE *
.\&quot; -----------------------------------------------------------------
.SH &quot;NAME&quot;
gitworkflows \- An overview of recommended workflows with Git
.SH &quot;SYNOPSIS&quot;
.sp
.nf
git *
.fi
.sp
.SH &quot;DESCRIPTION&quot;
.sp
This document attempts to write down and motivate some of the workflow elements used for \fBgit\&amp;.git\fR itself\&amp;. Many ideas apply in general, though the full workflow is rarely required for smaller projects with fewer people involved\&amp;.
.sp
We formulate a set of \fIrules\fR for quick reference, while the prose tries to motivate each of them\&amp;. Do not always take them literally; you should value good reasons for your actions higher than manpages such as this one\&amp;.
.SH &quot;SEPARATE CHANGES&quot;
.sp
As a general rule, you should try to split your changes into small logical steps, and commit each of them\&amp;. They should be consistent, working independently of any later commits, pass the test suite, etc\&amp;. This makes the review process much easier, and the history much more useful for later inspection and analysis, for example with \fBgit-blame\fR(1) and \fBgit-bisect\fR(1)\&amp;.
.sp
To achieve this, try to split your work into small steps from the very beginning\&amp;. It is always easier to squash a few commits together than to split one big commit into several\&amp;. Don\(cqt be afraid of making too small or imperfect steps along the way\&amp;. You can always go back later and edit the commits with \fBgit\fR \fBrebase\fR \fB\-\-interactive\fR before you publish them\&amp;. You can use \fBgit\fR \fBstash\fR \fBpush\fR \fB\-\-keep\-index\fR to run the test suite independent of other uncommitted changes; see the EXAMPLES section of \fBgit-stash\fR(1)\&amp;.
.SH &quot;MANAGING BRANCHES&quot;
.sp
There are two main tools that can be used to include changes from one branch on another: \fBgit-merge\fR(1) and \fBgit-cherry-pick\fR(1)\&amp;.
.sp
Merges have many advantages, so we try to solve as many problems as possible with merges alone\&amp;. Cherry\-picking is still occasionally useful; see &quot;Merging upwards&quot; below for an example\&amp;.
.sp
Most importantly, merging works at the branch level, while cherry\-picking works at the commit level\&amp;. 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)\&amp;. Merges are also easier to understand because a merge commit is a &quot;promise&quot; that all changes from all its parents are now included\&amp;.
.sp
There is a tradeoff of course: merges require a more careful branch management\&amp;. The following subsections discuss the important points\&amp;.
.SS &quot;Graduation&quot;
.sp
As a given feature goes from experimental to stable, it also &quot;graduates&quot; between the corresponding branches of the software\&amp;. \fBgit\&amp;.git\fR uses the following \fIintegration branches\fR:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fImaint\fR
tracks the commits that should go into the next &quot;maintenance release&quot;, i\&amp;.e\&amp;., update of the last released stable version;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fImaster\fR
tracks the commits that should go into the next release;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fInext\fR
is intended as a testing branch for topics being tested for stability for master\&amp;.
.RE
.sp
There is a fourth official branch that is used slightly differently:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIseen\fR
(patches seen by the maintainer) is an integration branch for things that are not quite ready for inclusion yet (see &quot;Integration Branches&quot; below)\&amp;.
.RE
.sp
Each of the four branches is usually a direct descendant of the one above it\&amp;.
.sp
Conceptually, the feature enters at an unstable branch (usually \fInext\fR or \fIseen\fR), and &quot;graduates&quot; to \fImaster\fR for the next release once it is considered stable enough\&amp;.
.SS &quot;Merging upwards&quot;
.sp
The &quot;downwards graduation&quot; discussed above cannot be done by actually merging downwards, however, since that would merge \fIall\fR changes on the unstable branch into the stable one\&amp;. Hence the following:
.PP
\fBExample\ \&amp;1.\ \&amp;Merge upwards\fR
.sp
Always commit your fixes to the oldest supported branch that requires them\&amp;. Then (periodically) merge the integration branches upwards into each other\&amp;.
.sp
This gives a very controlled flow of fixes\&amp;. If you notice that you have applied a fix to e\&amp;.g\&amp;. \fImaster\fR that is also required in \fImaint\fR, you will need to cherry\-pick it (using \fBgit-cherry-pick\fR(1)) downwards\&amp;. This will happen a few times and is nothing to worry about unless you do it very frequently\&amp;.
.SS &quot;Topic branches&quot;
.sp
Any nontrivial feature will require several patches to implement, and may get extra bugfixes or improvements during its lifetime\&amp;.
.sp
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\&amp;. Working in parallel mixes up the changes, creating further confusion\&amp;.
.sp
Use of &quot;topic branches&quot; solves these problems\&amp;. The name is pretty self explanatory, with a caveat that comes from the &quot;merge upwards&quot; rule above:
.PP
\fBExample\ \&amp;2.\ \&amp;Topic branches\fR
.sp
Make a side branch for every topic (feature, bugfix, \&amp;...)\&amp;. Fork it off at the oldest integration branch that you will eventually want to merge it into\&amp;.
.sp
Many things can then be done very naturally:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
To get the feature/bugfix into an integration branch, simply merge it\&amp;. If the topic has evolved further in the meantime, merge again\&amp;. (Note that you do not necessarily have to merge it to the oldest integration branch first\&amp;. For example, you can first merge a bugfix to
\fInext\fR, give it some testing time, and merge to
\fImaint\fR
when you know it is stable\&amp;.)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
If you find you need new features from the branch
\fIother\fR
to continue working on your topic, merge
\fIother\fR
to
\fItopic\fR\&amp;. (However, do not do this &quot;just habitually&quot;, see below\&amp;.)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
If you find you forked off the wrong branch and want to move it &quot;back in time&quot;, use
\fBgit-rebase\fR(1)\&amp;.
.RE
.sp
Note that the last point clashes with the other two: a topic that has been merged elsewhere should not be rebased\&amp;. See the section on RECOVERING FROM UPSTREAM REBASE in \fBgit-rebase\fR(1)\&amp;.
.sp
We should point out that &quot;habitually&quot; (regularly for no real reason) merging an integration branch into your topics \(em and by extension, merging anything upstream into anything downstream on a regular basis \(em is frowned upon:
.PP
\fBExample\ \&amp;3.\ \&amp;Merge to downstream only at well\-defined points\fR
.sp
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\&amp;.
.sp
Otherwise, the topic that was merged to suddenly contains more than a single (well\-separated) change\&amp;. The many resulting small merges will greatly clutter up history\&amp;. Anyone who later investigates the history of a file will have to find out whether that merge affected the topic in development\&amp;. An upstream might even inadvertently be merged into a &quot;more stable&quot; branch\&amp;. And so on\&amp;.
.SS &quot;Throw\-away integration&quot;
.sp
If you followed the last paragraph, you will now have many small topic branches, and occasionally wonder how they interact\&amp;. Perhaps the result of merging them does not even work? But on the other hand, we want to avoid merging them anywhere &quot;stable&quot; because such merges cannot easily be undone\&amp;.
.sp
The solution, of course, is to make a merge that we can undo: merge into a throw\-away branch\&amp;.
.PP
\fBExample\ \&amp;4.\ \&amp;Throw\-away integration branches\fR
.sp
To test the interaction of several topics, merge them into a throw\-away branch\&amp;. You must never base any work on such a branch!
.sp
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\&amp;. \fBgit\&amp;.git\fR has such an official throw\-away integration branch called \fIseen\fR\&amp;.
.SS &quot;Branch management for a release&quot;
.sp
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\&amp;.
.sp
A feature release is created from the \fImaster\fR branch, since \fImaster\fR tracks the commits that should go into the next feature release\&amp;.
.sp
The \fImaster\fR branch is supposed to be a superset of \fImaint\fR\&amp;. If this condition does not hold, then \fImaint\fR contains some commits that are not included on \fImaster\fR\&amp;. The fixes represented by those commits will therefore not be included in your feature release\&amp;.
.sp
To verify that \fImaster\fR is indeed a superset of \fImaint\fR, use git log:
.PP
\fBExample\ \&amp;5.\ \&amp;Verify \fImaster\fR is a superset of \fImaint\fR\fR
.sp
\fBgit\fR \fBlog\fR \fBmaster\fR\fB\&amp;.\&amp;.\fR\fBmaint\fR
.sp
This command should not list any commits\&amp;. Otherwise, check out \fImaster\fR and merge \fImaint\fR into it\&amp;.
.sp
Now you can proceed with the creation of the feature release\&amp;. Apply a tag to the tip of \fImaster\fR indicating the release version:
.PP
\fBExample\ \&amp;6.\ \&amp;Release tagging\fR
.sp
\fBgit\fR \fBtag\fR \fB\-s\fR \fB\-m\fR &quot;Git \fBX\&amp;.Y\&amp;.Z\fR&quot; \fBvX\&amp;.Y\&amp;.Z\fR \fBmaster\fR
.sp
You need to push the new tag to a public Git server (see &quot;DISTRIBUTED WORKFLOWS&quot; below)\&amp;. This makes the tag available to others tracking your project\&amp;. The push could also trigger a post\-update hook to perform release\-related items such as building release tarballs and preformatted documentation pages\&amp;.
.sp
Similarly, for a maintenance release, \fImaint\fR is tracking the commits to be released\&amp;. Therefore, in the steps above simply tag and push \fImaint\fR rather than \fImaster\fR\&amp;.
.SS &quot;Maintenance branch management after a feature release&quot;
.sp
After a feature release, you need to manage your maintenance branches\&amp;.
.sp
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\&amp;.
.sp
To do this, the current maintenance branch is copied to another branch named with the previous release version number (e\&amp;.g\&amp;. maint\-X\&amp;.Y\&amp;.(Z\-1) where X\&amp;.Y\&amp;.Z is the current release)\&amp;.
.PP
\fBExample\ \&amp;7.\ \&amp;Copy maint\fR
.sp
\fBgit\fR \fBbranch\fR \fBmaint\-X\&amp;.Y\&amp;.\fR(\fBZ\-1\fR) \fBmaint\fR
.sp
The \fImaint\fR branch should now be fast\-forwarded to the newly released code so that maintenance fixes can be tracked for the current release:
.PP
\fBExample\ \&amp;8.\ \&amp;Update maint to new release\fR
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBgit\fR
\fBcheckout\fR
\fBmaint\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBgit\fR
\fBmerge\fR
\fB\-\-ff\-only\fR
\fBmaster\fR
.RE
.sp
If the merge fails because it is not a fast\-forward, then it is possible some fixes on \fImaint\fR were missed in the feature release\&amp;. This will not happen if the content of the branches was verified as described in the previous section\&amp;.
.SS &quot;Branch management for next and seen after a feature release&quot;
.sp
After a feature release, the integration branch \fInext\fR may optionally be rewound and rebuilt from the tip of \fImaster\fR using the surviving topics on \fInext\fR:
.PP
\fBExample\ \&amp;9.\ \&amp;Rewind and rebuild next\fR
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBgit\fR
\fBswitch\fR
\fB\-C\fR
\fBnext\fR
\fBmaster\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBgit\fR
\fBmerge\fR
\fBai/topic_in_next1\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBgit\fR
\fBmerge\fR
\fBai/topic_in_next2\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\&amp;...
.RE
.sp
The advantage of doing this is that the history of \fInext\fR will be clean\&amp;. For example, some topics merged into \fInext\fR may have initially looked promising, but were later found to be undesirable or premature\&amp;. In such a case, the topic is reverted out of \fInext\fR but the fact remains in the history that it was once merged and reverted\&amp;. By recreating \fInext\fR, 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\&amp;.
.sp
If you do this, then you should make a public announcement indicating that \fInext\fR was rewound and rebuilt\&amp;.
.sp
The same rewind and rebuild process may be followed for \fIseen\fR\&amp;. A public announcement is not necessary since \fIseen\fR is a throw\-away branch, as described above\&amp;.
.SH &quot;DISTRIBUTED WORKFLOWS&quot;
.sp
After the last section, you should know how to manage topics\&amp;. In general, you will not be the only person working on the project, so you will have to share your work\&amp;.
.sp
Roughly speaking, there are two important workflows: merge and patch\&amp;. The important difference is that the merge workflow can propagate full history, including merges, while patches cannot\&amp;. Both workflows can be used in parallel: in \fBgit\&amp;.git\fR, only subsystem maintainers use the merge workflow, while everyone else sends patches\&amp;.
.sp
Note that the maintainer(s) may impose restrictions, such as &quot;Signed\-off\-by&quot; requirements, that all commits/patches submitted for inclusion must adhere to\&amp;. Consult your project\(cqs documentation for more information\&amp;.
.SS &quot;Merge workflow&quot;
.sp
The merge workflow works by copying branches between upstream and downstream\&amp;. Upstream can merge contributions into the official history; downstream base their work on the official history\&amp;.
.sp
There are three main tools that can be used for this:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBgit-push\fR(1)
copies your branches to a remote repository, usually to one that can be read by all involved parties;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBgit-fetch\fR(1)
that copies remote branches to your repository; and
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBgit-pull\fR(1)
that does fetch and merge in one go\&amp;.
.RE
.sp
Note the last point\&amp;. Do \fInot\fR use \fIgit pull\fR unless you actually want to merge the remote branch\&amp;.
.sp
Getting changes out is easy:
.PP
\fBExample\ \&amp;10.\ \&amp;Push/pull: Publishing branches/topics\fR
.sp
\fBgit\fR \fBpush\fR \fI&lt;remote&gt;\fR \fI&lt;branch&gt;\fR and tell everyone where they can fetch from\&amp;.
.sp
You will still have to tell people by other means, such as mail\&amp;. (Git provides the \fBgit-request-pull\fR(1) to send preformatted pull requests to upstream maintainers to simplify this task\&amp;.)
.sp
If you just want to get the newest copies of the integration branches, staying up to date is easy too:
.PP
\fBExample\ \&amp;11.\ \&amp;Push/pull: Staying up to date\fR
.sp
Use \fBgit\fR \fBfetch\fR \fI&lt;remote&gt;\fR or \fBgit\fR \fBremote\fR \fBupdate\fR to stay up to date\&amp;.
.sp
Then simply fork your topic branches from the stable remotes as explained earlier\&amp;.
.sp
If you are a maintainer and would like to merge other people\(cqs topic branches to the integration branches, they will typically send a request to do so by mail\&amp;. Such a request looks like
.sp
.if n \{\
.RS 4
.\}
.nf
Please pull from
    &lt;URL&gt; &lt;branch&gt;
.fi
.if n \{\
.RE
.\}
.sp
.sp
In that case, \fIgit pull\fR can do the fetch and merge in one go, as follows\&amp;.
.PP
\fBExample\ \&amp;12.\ \&amp;Push/pull: Merging remote topics\fR
.sp
\fBgit\fR \fBpull\fR \fI&lt;URL&gt;\fR \fI&lt;branch&gt;\fR
.sp
Occasionally, the maintainer may get merge conflicts when they try to pull changes from downstream\&amp;. 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)\&amp;. It is one of the rare cases where downstream \fIshould\fR merge from upstream\&amp;.
.SS &quot;Patch workflow&quot;
.sp
If you are a contributor that sends changes upstream in the form of emails, you should use topic branches as usual (see above)\&amp;. Then use \fBgit-format-patch\fR(1) to generate the corresponding emails (highly recommended over manually formatting them because it makes the maintainer\(cqs life easier)\&amp;.
.PP
\fBExample\ \&amp;13.\ \&amp;format\-patch/am: Publishing branches/topics\fR
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBgit\fR
\fBformat\-patch\fR
\fB\-M\fR
\fBupstream\fR\fB\&amp;.\&amp;.\fR\fBtopic\fR
to turn them into preformatted patch files
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBgit\fR
\fBsend\-email\fR
\fB\-\-to=\fR\fI&lt;recipient&gt;\fR
\fI&lt;patches&gt;\fR
.RE
.sp
See the \fBgit-format-patch\fR(1) and \fBgit-send-email\fR(1) manpages for further usage notes\&amp;.
.sp
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):
.PP
\fBExample\ \&amp;14.\ \&amp;format\-patch/am: Keeping topics up to date\fR
.sp
\fBgit\fR \fBpull\fR \fB\-\-rebase\fR \fI&lt;URL&gt;\fR \fI&lt;branch&gt;\fR
.sp
You can then fix the conflicts during the rebase\&amp;. Presumably you have not published your topic other than by mail, so rebasing it is not a problem\&amp;.
.sp
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 \fIgit am\fR to import the commits:
.PP
\fBExample\ \&amp;15.\ \&amp;format\-patch/am: Importing patches\fR
.sp
\fBgit\fR \fBam\fR &lt; \fBpatch\fR
.sp
One feature worth pointing out is the three\-way merge, which can help if you get conflicts: \fBgit\fR \fBam\fR \fB\-3\fR will use index information contained in patches to figure out the merge base\&amp;. See \fBgit-am\fR(1) for other options\&amp;.
.SH &quot;SEE ALSO&quot;
.sp
\fBgittutorial\fR(7), \fBgit-push\fR(1), \fBgit-pull\fR(1), \fBgit-merge\fR(1), \fBgit-rebase\fR(1), \fBgit-format-patch\fR(1), \fBgit-send-email\fR(1), \fBgit-am\fR(1)
.SH &quot;GIT&quot;
.sp
Part of the \fBgit\fR(1) suite
</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Fusr%2Flocal%2Fcpanel%2F3rdparty%2Fshare%2Fman%2Fman7'>Back to Directory</a>