Commits

Yujie Wu  committed d26d95b

Updated documentation for v0.9.4.

  • Participants
  • Parent commits a5f5511

Comments (0)

Files changed (2)

File DetailedCommands.wiki

 <<toc 3>>
 = Detailed Commands =
 == Master ==
+Master stream contains 1 and only 1 branch that has only and all production
+revisions (i.e., official releases). New revisions in <master> are created when
+a <release> or <hotfix> branch merges into <master>.
+The actions that can be applied to <master> include: push, publish, pull, list,
+and log.
+
 === push ===
+This command will push only the master branch to the remote repository.
 Change your workspace to the master branch, then call the following command.
 {{{
 #!bash
 hg flow master push
 }}}
-\\
-This command will push only the master branch to the remote repository.
 
 === publish ===
 An alias of the ##**push**## action
 
 === pull ===
+Pull the master branch from the remote repository. Change your workspace
+to the master branch, then call the following command.
 {{{
 #!bash
 hg flow master pull
 }}}
-\\
-Pull the master branch from the remote repository.
 
 === log ===
+Show the revision history of the master branch. If a file name is specified, show revision history of the file in the master branch.
 {{{
 #!bash
-hg flow master log [<file-name>]
+hg flow master log [-F [<file-name>] | <file-name>] [<option>...]
 }}}
-\\
-Show the log of the master branch. If a file name is specified, show the log of the file in the master branch.
+
+Options:
+{{{
+ -F --file FILE [+]  File to show history of.
+ -d --date DATE      Show revisions matching date spec.
+ -k --keyword TEXT   Do case-insensitive search for a given text.
+ -p --patch          Show patch.
+ -g --git            Use git extended diff format to show patch.
+ -l --limit VALUE    Limit number of changesets displayed.
+ 
+[+] marked option can be specified multiple times.
+}}}
 
 == Develop ==
+Develop stream contains all changes made for future releases. <release> and
+<feature> branches are started from <develop> and will be merged to <develop>
+when finished. Since version 0.9, user can create branches in
+<develop>. A <develop> branch can be used as the source branch to start
+<release> and <feature> branches.
+
 === push ===
+This command will push only the develop branch to the remote repository.
 Change your workspace to the develop branch, then call the following command.
 {{{
 #!bash
 hg flow develop push
 }}}
-\\
-This command will push only the develop branch to the remote repository.
 
 === publish ===
 An alias of the ##**push**## action
 
 === pull ===
+Pull the develop branch from the remote repository. Change your workspace
+to the develop branch, then call the following command.
 {{{
 #!bash
 hg flow develop pull 
 }}}
-\\
-Pull the develop branch from the remote repository. 
+
+=== list ===
+List all open branches in the develop stream.
+{{{
+#!bash
+hg flow develop list [<option>]
+}}}
+Markers:
+* ##** * **## indicates active branch (i.e., the current workspace).
+* ##** # **## indicates there are shelved changes in the branch.
+
+Option:
+{{{
+-c --closed    Show open and closed branches in <stream>.
+}}}
 
 === log ===
+Show revision history of the develop branch. If a file name is specified,
+show revision history of the file in the develop branch.
 {{{
 #!bash
-hg flow develop log [<file-name>]
+hg flow develop log [-F [<file-name>] | <file-name>] [<option>...]
 }}}
-\\
-Show the log of the develop branch. If a file name is specified, show the log of the file in the develop branch.
+
+Options:
+{{{
+ -F --file FILE [+]  File to show history of.
+ -d --date DATE      Show revisions matching date spec.
+ -k --keyword TEXT   Do case-insensitive search for a given text.
+ -p --patch          Show patch.
+ -g --git            Use git extended diff format to show patch.
+ -l --limit VALUE    Limit number of changesets displayed.
+
+[+] marked option can be specified multiple times.
+}}}
+
+=== abort ===
+Close the develop branch. Change your workspace to the develop branch, then call the following command.
+You cannot abort the develop trunk.
+{{{
+#!bash
+hg flow develop abort
+}}}
 
 == Feature ==
+Feature stream contains branches where new features for future releases are
+developed. Branches in <feature> are created from either <develop> or an
+existing <feature> branch.
+All actions can be applied to a <feature> branch. When a <feature> branch is
+finished, it will normally be merged into <develop>.
+
 === start ===
+Create a new feature branch from the ##**develop**## stream, and change the workspace to the new branch.
+The new branch will be named after ##<feature-branch-prefix>/<name>##.
 {{{
 #!bash
 hg flow feature start <name>
 }}}
-\\
-Create a new feature branch from the ##**develop**## stream, and change the workspace to the new branch.
-The new branch will be named after ##<feature-branch-prefix>/<name>##.
+
+Options:
+{{{
+ -r --rev REV       Revision to start a new branch from.
+ -m --message TEXT  Record TEXT as commit message when open new branch.
+ -d --date DATE     Record the specified DATE as commit date.
+}}}
 
 === finish ===
 Change your workspace to the feature branch that you want to finish, then call the following command.
+This command will merge the feature branch to the develop stream and then close the feature branch.
 {{{
 #!bash
 hg flow feature finish
 }}}
-\\
-This command will merge the feature branch to the develop stream and then close the feature branch.
+
+Options:
+{{{
+ -c --commit        Commit changes before close the branch.
+ -m --message TEXT  Record TEXT as commit message.
+ -d --date DATE     Record the specified DATE as commit date.
+}}}
 
 === push ===
+This command will push only the feature branch to the remote repository. 
 Change your workspace to the feature branch that you want to push, then call the following command.
 {{{
 #!bash
 hg flow feature push 
 }}}
-\\
-This command will push only the feature branch to the remote repository. 
 
 === publish ===
 An alias of the ##**push**## action
  
 === pull ===
+Pull a feature branch named <feature-stream-prefix>/<name> from the remote repository.
+If <name> is not specified, it will default to the current workspace branch.
 {{{
 #!bash
 hg flow feature pull [<name>]
 }}}
-\\
-Pull a feature branch called <name> from the remote repository. If <name> is not specified, it will default to
-your current workspace.
 
 === list ===
+List all open branches in the feature stream.
 {{{
 #!bash
-hg flow feature list
+hg flow feature list [<option>]
 }}}
-\\
-List all open branches in the feature stream.
 Markers:
 * ##** * **## indicates active branch (i.e., the current workspace).
 * ##** # **## indicates there are shelved changes in the branch.
 
+Option:
+{{{
+-c --closed    Show open and closed branches in <stream>.
+}}}
+
 === log ===
+Show the log of the feature branch called <name>. If <name> is not specified, it will default to
+the current workspace (which must be in the feature stream).
 {{{
 #!bash
-hg flow feature log [{<name>|<file-name>] [-F <file-name>]
+hg flow feature log [<name>|<file-name>] [-F <file-name>]
 }}}
-\\
-Show the log of the feature branch called <name>. If <name> is not specified, it will default to
-the current workspace (which must be in the feature stream). You can also let hgflow show the log
-of a particular file by specifying the file name:
+
+To show the log of a particular file, you can specify the file name:
 {{{
 #!bash
 hg flow feature log <file-name>
 }}}
-\\
 In this case, <file-name> must differ from the branch name. If they are the same, you can use the
 ##-F## option to avoid ambiguity:
 {{{
 hg flow feature <name> -F <file-name>
 }}}
 \\
+Options:
+{{{
+ -F --file FILE [+]  File to show history of.
+ -d --date DATE      Show revisions matching date spec.
+ -k --keyword TEXT   Do case-insensitive search for a given text.
+ -p --patch          Show patch.
+ -g --git            Use git extended diff format to show patch.
+ -l --limit VALUE    Limit number of changesets displayed.
+
+[+] marked option can be specified multiple times.
+}}}
 
 === rebase ===
+Rebase the current branch to the develop branch. If the destination is specified, the command
+will rebase the current branch to it. The destination must be in the develop branch. If it is not
+specified, the command will rebase to the head of the develop branch.
 {{{
 #!bash
 hg flow feature rebase [-d <REV>]
 }}}
-\\
-Rebase the current branch to the develop branch. If the destination is specified, the command
-will rebase the current branch to it. The destination must be in the develop branch. If it is not
-specified, the command will rebase to the tip of the develop branch.
+
+=== promote ===
+Merge the workspace branch to destination branches. The destination branches,
+if omitted, will default to the trunk of <develop>.
+{{{
+#!bash
+hg flow feature promote [branch...] [<option>...]
+}}}
+
+Options:
+{{{
+-r --rev REV       Revision to promote to other branches.
+-m --message TEXT  Record TEXT as commit message when promote branch.
+-d --date DATE     Record the specified DATE as commit date.
+}}}
+The workspace branch must be in the feature stream. If the `-r` option is omitted, its
+value will default to the head of the workspace branch.
+
+=== abort ===
+Close the feature branch. Change your workspace to the feature branch, then call the following command.
+{{{
+#!bash
+hg flow feature abort
+}}}
 
 == Release ==
+Release stream contains branches of release candidates. Code in <release> branch
+will usually be tested and bug-fixed. Once a <release> branch is graduated from
+the testing and bug-fixing process, it will be merged to both <master> and
+<develop>.
+
 === start ===
+Create a new release branch from the ##**develop**## stream, and change the workspace to the new branch.
+The new branch will be named after ##<release-branch-prefix>/<name>##.
 {{{
 #!bash
 hg flow release start <name>
 }}}
-\\
-Create a new release branch from the ##**develop**## stream, and change the workspace to the new branch.
-The new branch will be named after ##<release-branch-prefix>/<name>##.
+
+Options:
+{{{
+ -r --rev REV       Revision to start a new branch from.
+ -m --message TEXT  Record TEXT as commit message when open new branch.
+ -d --date DATE     Record the specified DATE as commit date.
+}}}
 
 === finish ===
+This command will merge the release branch to both the master and the develop streams and then close the release branch.
 Change your workspace to the release branch that you want to finish, then call the following command.
 {{{
 #!bash
 hg flow release finish
 }}}
-\\
-This command will merge the release branch to both the master and the develop streams and then close the release branch.
+
+Options:
+{{{
+ -c --commit        Commit changes before close the branch.
+ -m --message TEXT  Record TEXT as commit message.
+ -d --date DATE     Record the specified DATE as commit date.
+}}}
 
 === push ===
+This command will push only the release branch to the remote repository.
 Change your workspace to the release branch that you want to push, then call the following command.
 {{{
 #!bash
 hg flow release push
 }}}
-\\
-This command will push only the release branch to the remote repository.
 
 === publish ===
 An alias of the ##**push**## action
 
 === pull ===
+Pull a release branch called <release-stream-prefix>/<name> from the remote repository. If <name> is not specified, it will default to your current workspace. 
 {{{
 #!bash
 hg flow release pull [<name>]
 }}}
 \\
-Pull a release branch called <name> from the remote repository. If <name> is not specified, it will default to 
-your current workspace. 
 
 === list ===
+List all open branches in the release stream.
 {{{
 #!bash
-hg flow release list
+hg flow release list [<option>]
 }}}
-\\
-List all open branches in the release stream.
 Markers:
 * ##** * **## indicates active branch (i.e., the current workspace).
 * ##** # **## indicates there are shelved changes in the branch.
 
+Option:
+{{{
+-c --closed    Show open and closed branches in <stream>.
+}}}
+
 === log ===
+Show the log of the release branch called <name>. If <name> is not specified, it will default to
+the current workspace (which must be in the release stream).
 {{{
 #!bash
 hg flow release log [{<name>|<file-name>] [-F <file-name>]
 }}}
-\\
-Show the log of the release branch called <name>. If <name> is not specified, it will default to
-the current workspace (which must be in the release stream). You can also let hgflow show log
-of a particular file by specifying the file name:
+
+To show the log of a particular file, you can specify the file name:
 {{{
 #!bash
 hg flow release log <file-name>
 }}}
-\\
 In this case, <file-name> must differ from the branch name. If they are the same, you can use the
 ##-F## option to avoid ambiguity:
 {{{
 hg flow release <name> -F <file-name>
 }}}
 \\
+Options:
+{{{
+ -F --file FILE [+]  File to show history of.
+ -d --date DATE      Show revisions matching date spec.
+ -k --keyword TEXT   Do case-insensitive search for a given text.
+ -p --patch          Show patch.
+ -g --git            Use git extended diff format to show patch.
+ -l --limit VALUE    Limit number of changesets displayed.
+
+[+] marked option can be specified multiple times.
+}}}
 
 === rebase ===
+Rebase the current branch to the develop branch. If the destination is specified, the command
+will rebase the current branch to it. The destination must be in the develop branch. If it is not
+specified, the command will rebase to the tip of the develop branch.
 {{{
 #!bash
 hg flow release rebase [-d <REV>]
 }}}
-\\
-Rebase the current branch to the develop branch. If the destination is specified, the command
-will rebase the current branch to it. The destination must be in the develop branch. If it is not
-specified, the command will rebase to the tip of the develop branch.
+
+=== promote ===
+Merge the workspace branch to destination branches. The destination branches,
+if omitted, will default to the trunks of <master> and <develop>.
+{{{
+#!bash
+hg flow release promote [branch...] [<option>...]
+}}}
+
+Options:
+{{{
+-r --rev REV       Revision to promote to other branches.
+-m --message TEXT  Record TEXT as commit message when promote branch.
+-d --date DATE     Record the specified DATE as commit date.
+}}}
+The workspace branch must be in <stream>. If the `-r` option is omitted, its
+value will default to the head of the workspace branch.
 
 == Hotfix ==
+Hotfix stream contains branches for fixing bugs in <master>. <hotfix> branches
+are started from <master> and once they are finished will be merged to both
+<master> and <develop>.
+
 === start ===
+Create a new hotfix branch from the ##**master**## stream, and change the workspace to the new branch.
+The new branch will be named after ##<hotfix-branch-prefix>/<name>##.
 {{{
 #!bash
 hg flow hotfix start <name>
 }}}
-\\
-Create a new hotfix branch from the ##**master**## stream, and change the workspace to the new branch.
-The new branch will be named after ##<hotfix-branch-prefix>/<name>##.
+
+Options:
+{{{
+ -r --rev REV       Revision to start a new branch from.
+ -m --message TEXT  Record TEXT as commit message when open new branch.
+ -d --date DATE     Record the specified DATE as commit date.
+}}}
 
 === finish ===
 Change your workspace to the hotfix branch that you want to finish, then call the following command.
+This command will merge the release branch to both the master and the develop streams and then close the hotfix branch.
 {{{
 #!bash
 hg flow hotfix finish
 }}}
-\\
-This command will merge the release branch to both the master and the develop streams and then close the hotfix branch.
+
+Options:
+{{{
+ -c --commit        Commit changes before close the branch.
+ -m --message TEXT  Record TEXT as commit message.
+ -d --date DATE     Record the specified DATE as commit date.
+}}}
 
 === push ===
+This command will push only the hotfix branch to the remote repository.
 Change your workspace to the hotfix branch that you want to push, then call the following command.
 {{{
 #!bash
 hg flow hotfix push
 }}}
-\\
-This command will push only the hotfix branch to the remote repository.
 
 === publish ===
 An alias of the ##**push**## action
 
 === pull ===
+Pull a hotfix branch called <name> from the remote repository. If <name> is not specified, it will default to
+the current workspace.
 {{{
 #!bash
 hg flow hotfix pull [<name>]
 }}}
-\\
-Pull a hotfix branch called <name> from the remote repository. If <name> is not specified, it will default to
-your current workspace.
 
 === list ===
+List all open branches in the hotfix stream.
 {{{
 #!bash
 hg flow hotfix list
 }}}
-\\
-List all open branches in the hotfix stream.
+
 Markers:
 * ##** * **## indicates active branch (i.e., the current workspace).
 * ##** # **## indicates there are shelved changes in the branch.
 
+Option:
+{{{
+-c --closed    Show open and closed branches in <stream>.
+}}}
+
 === log ===
+Show the log of the hotfix branch called <name>. If <name> is not specified, it will default to
+the current workspace (which must be in the hotfix stream).
 {{{
 #!bash
 hg flow hotfix log [{<name>|<file-name>] [-F <file-name>]
 }}}
-\\
-Show the log of the hotfix branch called <name>. If <name> is not specified, it will default to
-the current workspace (which must be in the hotfix stream). You can also let hgflow show the log
-of a particular file by specifying the file name:
+
+To show the log of a particular file, you can specify the file name:
 {{{
 #!bash
 hg flow hotfix log <file-name>
 hg flow hotfix <name> -F <file-name>
 }}}
 \\
+Options:
+{{{
+ -F --file FILE [+]  File to show history of.
+ -d --date DATE      Show revisions matching date spec.
+ -k --keyword TEXT   Do case-insensitive search for a given text.
+ -p --patch          Show patch.
+ -g --git            Use git extended diff format to show patch.
+ -l --limit VALUE    Limit number of changesets displayed.
+
+[+] marked option can be specified multiple times.
+}}}
 
 === rebase ===
+Rebase the current branch to the master branch. If the destination is specified, the command
+will rebase the current branch to it. The destination must be in the master branch. If it is not
+specified, the command will rebase to the head of the master branch.
 {{{
 #!bash
 hg flow hotfix rebase [-d <REV>]
 }}}
-\\
-Rebase the current branch to the master branch. If the destination is specified, the command
-will rebase the current branch to it. The destination must be in the master branch. If it is not
-specified, the command will rebase to the tip of the master branch.
+
+=== promote ===
+Merge the workspace branch to destination branches. The destination branches,
+if omitted, will default to the trunks of <master> and <develop>.
+{{{
+#!bash
+hg flow hotfix promote [branch...] [<option>...]
+}}}
+
+Options:
+{{{
+-r --rev REV       Revision to promote to other branches.
+-m --message TEXT  Record TEXT as commit message when promote branch.
+-d --date DATE     Record the specified DATE as commit date.
+}}}
+The workspace branch must be in the hotfix stream. If the `-r` option is omitted, its
+value will default to the head of the workspace branch.
+
 
 == Support ==
+Support stream contains branches for supporting a previous release. <support>
+branches are started from <master> and will never be merged to anywhere. When
+they are finished, they will be simply closed.
+
 === start ===
+Create a new support branch from the ##**master**## stream, and change the workspace to the new branch.
+The new branch will be named after ##<support-branch-prefix>/<name>##.
 {{{
 #!bash
 hg flow support start <name>
 }}}
-\\
-Create a new support branch from the ##**master**## stream, and change the workspace to the new branch.
-The new branch will be named after ##<support-branch-prefix>/<name>##.
+
+Options:
+{{{
+ -r --rev REV       Revision to start a new branch from.
+ -m --message TEXT  Record TEXT as commit message when open new branch.
+ -d --date DATE     Record the specified DATE as commit date.
+}}}
 
 === finish ===
+This command will simply close the support branch.
 Change your workspace to the support branch that you want to finish, then call the following command.
 {{{
 #!bash
 hg flow support finish
 }}}
-\\
-This command will simply close the support branch.
+
+Options:
+{{{
+ -c --commit        Commit changes before close the branch.
+ -m --message TEXT  Record TEXT as commit message.
+ -d --date DATE     Record the specified DATE as commit date.
+}}}
 
 === push ===
+This command will push only the support branch to the remote repository.
 Change your workspace to the support branch that you want to push, then call the following command.
 {{{
 #!bash
 hg flow support push
 }}}
-\\
-This command will push only the support branch to the remote repository.
 
 === publish ===
 An alias of the ##**push**## action
 
 === pull ===
+Pull a support branch called <name> from the remote repository. If <name> is not specified, it will default to
+the current workspace.
 {{{
 #!bash
 hg flow support pull [<name>]
 }}}
-\\
-Pull a support branch called <name> from the remote repository. If <name> is not specified, it will default to
-your current workspace.
 
 === list ===
+List all open branches in the support stream.
 {{{
 #!bash
 hg flow support list
 }}}
-\\
-List all open branches in the release stream.
 Markers:
 * ##** * **## indicates active branch (i.e., the current workspace).
 * ##** # **## indicates there are shelved changes in the branch.
 
+Option:
+{{{
+-c --closed    Show open and closed branches in <stream>.
+}}}
+
 === log ===
+Show the log of the support branch called <name>. If <name> is not specified, it will default to
+the current workspace (which must be in the support stream).
 {{{
 #!bash
 hg flow support log [{<name>|<file-name>] [-F <file-name>]
 }}}
-\\
-Show the log of the support branch called <name>. If <name> is not specified, it will default to
-the current workspace (which must be in the hotfix stream). You can also let hgflow show the log
-of a particular file by specifying the file name:
+
+To show the log of a particular file, you can specify the file name:
 {{{
 #!bash
 hg flow support log <file-name>
 hg flow support <name> -F <file-name>
 }}}
 \\
+Options:
+{{{
+ -F --file FILE [+]  File to show history of.
+ -d --date DATE      Show revisions matching date spec.
+ -k --keyword TEXT   Do case-insensitive search for a given text.
+ -p --patch          Show patch.
+ -g --git            Use git extended diff format to show patch.
+ -l --limit VALUE    Limit number of changesets displayed.
+
+[+] marked option can be specified multiple times.
+}}}
 
 === rebase ===
+Rebase the current branch to the master branch. If the destination is specified, the command
+will rebase the current branch to it. The destination must be in the master branch. If it is not
+specified, the command will rebase to the head of the master branch.
 {{{
 #!bash
 hg flow support rebase [-d <REV>]
 }}}
-\\ 
-Rebase the current branch to the master branch. If the destination is specified, the command
-will rebase the current branch to it. The destination must be in the master branch. If it is not
-specified, the command will rebase to the tip of the master branch.
+
+=== promote ===
+Merge the workspace branch to destination branches. The destination branches,
+if omitted, will default to the trunks of <master> and <develop>.
+{{{
+#!bash
+hg flow release promote [branch...] [<option>...]
+}}}
+
+Options:
+{{{
+-r --rev REV       Revision to promote to other branches.
+-m --message TEXT  Record TEXT as commit message when promote branch.
+-d --date DATE     Record the specified DATE as commit date.
+}}}
+The workspace branch must be in <stream>. If the `-r` option is omitted, its
+value will default to the head of the workspace branch.
 
 == Other Commands ==
 === Change to a stream ===
 |**upgrade** | Upgrade the configuration file to v0.9 or later.|
 |**help**    | Show help for a specific topic. Example: {{{hg flow help @help}}}|
 |**version** | Show flow's version number.|
-
-== Detailed commands ==
-[[DetailedCommands]] (Note: The detailed-commands page is not yet updated to include new features in 0.9.x.)
 \\
 \\
 \\