Skip to content

Latest commit

 

History

History
106 lines (74 loc) · 3.85 KB

git-topics.1.md

File metadata and controls

106 lines (74 loc) · 3.85 KB

git-topics(1) -- Manage topic branches

SYNOPSIS

git topics [] []

DESCRIPTION

git topics provides a collection of high-level commands that make it easy to manage topic branches roughly as described in gitworkflows(7). [BRANCHING MODEL][] gives an overview of the workflow in broad terms. The [COMMANDS][] section provides a summary of available commands.

BRANCHING MODEL

The core model is a simplification of the workflow described in gitworkflows(7). There are two main branches:

  • master: The primary, production-ready branch that tracks stable releases of the project. Commits here may be shipped at any time.

  • develop: An integration branch based on master that is used to test changes before their inclusion in master.

The names of these branches don't really matter. In fact, they are configurable, since there are many reasonable options. The documentation will refer to them by these canonical names, though.

Commits should not generally be made directly on either of the main branches. Instead, each isolated topic (feature, bug fix, etc) should be worked on in its own branch. Each topic branch should fork off of master, since the eventual goal is to merge it back into a stable version. Each topic branch is named something semantically meaningful, possibly with some conventional prefix. For example, if John Doe is working on a topic "foo", he might reasonably name the branch simply foo, prefix it by a keyword like topic/foo or feature-foo, or maybe prefix it by his initials like jd/foo. The important thing is that your project's convention is consistent and useful.

The general life cycle of a topic branch then goes:

  1. Fork your local topic branch off of master.

  2. Work on your topic.

  3. When you're ready, you may opt to push your topic branch remotely for others to review.

  4. When the review is complete and your topic branch is reasonably stable, you can integrate your changes by merging the topic branch into develop. This branch should then be used as a "playground" to test the new changes. Note that the topic branch DOES NOT get deleted at this point, in case testing reveals further changes you have to make.

  5. If your topic requires further changes, add additional commits to the topic branch. Repeat 2-4 until your changes are completely stable.

  6. When your topic is stable, you can merge it into master. The topic branch can then be deleted.

Releases of the project are cut from master by simply tagging a particular commit with a semantic version.

While you can carry out all of the above "by hand" pretty easily with normal git commands, git topics makes it slightly more convenient to follow this practice while providing some other goodies.

COMMANDS

  • git topics help []: Displays in-depth help for (or this page, if no command is given).

  • git topics setup [-f|--force]: Interactively configures the current repository so you can use all the other git topics commands. You should only need to run this command once. If you misconfigured something or there was an error, you can start over with the --force flag.

  • git topics: Shorthand for git topics list.

  • git topics list [-a|--all] [-r|--remote] [-s|--short] [-p|--porcelain]: List existing topic branches and their statuses.

  • git topics start : Start a new topic branch.

  • git topics review : Push a topic branch upstream for review.

  • git topics integrate : Merge a topic branch to the integration branch.

  • git topics finish : Merge a topic branch to the stable branch for release.

  • git topics release [major|minor|patch]: Tag the stable branch with a new version.

  • git topics reintegrate [--onto ]: Rewind & rebuild an integration branch.

SEE ALSO

git(1), gitworkflows(7), git-topics-management(7)