Merge pull request #190 from ajoberstar/documentation

more documentation

docs/content/grgit-add.ad

@@ -0,0 +1,65 @@
+= grgit-add
+:jbake-title: grgit-add
+:jbake-type: page
+:jbake-status: published
+
+== Name
+
+grgit-add - Add file contents to the index
+
+== Synopsis
+
+[source, groovy]
+----
+grgit.add(patterns: ['<path>', ...], update: <boolean>)
+----
+
+[source, groovy]
+----
+grgit.add {
+  patterns = ['<path>', ...]
+  update = <boolean>
+}
+----
+
+== Description
+
+This command updates the index using the current content found in the working tree, to prepare the content staged for the next commit. It typically adds the current content of existing paths as a whole, but with some options it can also be used to remove paths that do not exist in the working tree anymore.
+
+The "index" holds a snapshot of the content of the working tree, and it is this snapshot that is taken as the contents of the next commit. Thus after making any changes to the working tree, and before running the commit command, you must use the add command to add any new or modified files to the index.
+
+This command can be performed multiple times before a commit. It only adds the content of the specified file(s) at the time the add command is run; if you want subsequent changes included in the next commit, then you must run `add` again to add the new content to the index.
+
+The link:grgit-status.html[grgit-status] command can be used to obtain a summary of which files have changes that are staged for the next commit.
+
+Please see link:grgit-commit.html[grgit-commit] for alternative ways to add content to a commit.
+
+== Options
+
+patterns:: (`Set<String>`, default `[]`) Files to add content from. A leading directory name (e.g. `dir` to add `dir/file1` and `dir/file2`) can be given to update the index to match the current state of the directory as a whole (e.g. specifying `dir` will record not just a file `dir/file1` modified in the working tree, a file `dir/file2` added to the working tree, but also a file `dir/file3` removed from the working tree.
+update:: (`boolean`, default `false`) Update the index just where it already has an entry matching `patterns`. This removes as well as modifies index entries to match the working tree, but adds no new files.
++
+If no `pathspec` is given when `update` option is used, all tracked files in the entire working tree are updated.
+
+== Examples
+
+To add specific files or directories to the path. Wildcards are not supported.
+
+[source, groovy]
+----
+grgit.add(patterns: ['1.txt', 'some/dir'])
+----
+
+To add changes to all currently tracked files.
+
+[source, groovy]
+----
+grgit.add(update: true)
+----
+
+== See Also
+
+- link:https://git-scm.com/docs/git-add[git-add]
+- link:grgit-remove.html[grgit-remove]
+- link:grgit-commit.html[grgit-commit]
+- link:grgit-status.html[grgit-status]

docs/content/authentication.ad → docs/content/grgit-authentication.ad

@@ -37,7 +37,7 @@ These are presented in precedence order (direct parameter in code, system proper
 
 ==== Parameter to Grgit operations
 
-Some Grgit operations, such as link:clone.html[clone] allow you to provide credentials programmatically.
+Some Grgit operations, such as link:grgit-clone.html[grgit-clone] allow you to provide credentials programmatically.
 
 [source, groovy]
 ----

docs/content/grgit-branch.ad

@@ -0,0 +1,189 @@
+= grgit-branch
+:jbake-title: grgit-branch
+:jbake-type: page
+:jbake-status: published
+
+== Name
+
+grgit-branch - List, create, or delete branches
+
+== Synopsis
+
+[source, groovy]
+----
+grgit.branch.current()
+----
+
+[source, groovy]
+----
+grgit.branch.list()
+grgit.branch.list(mode: <mode>, contains: <commit>)
+----
+
+[source, groovy]
+----
+grgit.branch.add(name: <name>, startPoint: <startPoint>, mode: <mode>)
+----
+
+[source, groovy]
+----
+grgit.branch.change(name: <name>, startPoint: <startPoint>, mode: <mode>)
+----
+
+[source, groovy]
+----
+grgit.branch.remove(names: [<name>, ...], force: <boolean>)
+----
+
+== Description
+
+
+`grgit.branch.current()`:: Returns the current link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Branch.html[Branch].
+`grgit.branch.list()`:: Returns a list of branches (link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Branch.html[Branch]). The branches returned can be filtered using `mode` and `contains`.
+`grgit.branch.add(name: <name>, startPoint: <startPoint>, mode: <mode>)`:: Creates a new branch named `<name>` pointing at `<startPoint>`, possibly tracking a remote depending on `<mode>`. Returns the created link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Branch.html[Branch].
+`grgit.branch.change(name: <name>, startPoint: <startPoint>, mode: <mode>)`:: Modify an existing branch named `<name>` pointing at `<startPoint>`, possibly tracking a remote depending on `<mode>`. Returns the modified link:http://ajoberstar.org/grgit/docs/groovydoc/org/ajoberstar/grgit/Branch.html[Branch].
+`grgit.branch.remove(names: [<name>, ...], force: <boolean>)`:: Removes one or more branches. Returns a `List<String>` of branch names removed.
+
+== Options
+
+=== list
+
+mode:: (`String`, default `local`) Must be one of `local`, `remote`, `all`.
+`local`:::: Only list local branches (i.e. those under `refs/heads`)
+`remote`:::: Only list remote branches (i.e. those under `refs/remotes`)
+`all`:::: List all branches
+contains:: (`Object`, default `null`) Only list branches which contain the specified commit.  (`Object`, default `null`) Start the new branch at this commit. For a more complete list of acceptable inputs, see link:grgit-resolve.html[grgit-resolve] (specifically the `toRevisionString` method).
+
+=== add or change
+
+name:: (`String`, default `null`) Name of the branch
+startPoint:: (`Object`, default `null`) Start the new branch at this commit. For a more complete list of acceptable inputs, see link:grgit-resolve.html[grgit-resolve] (specifically the `toRevisionString` method).
+mode:: (`String`, default `null`) Must be one of `'track'` or `'no-track'` or `null`
+`track`:::: When creating a new branch, set up `branch.<name>.remote` and `branch.<name>.merge` configuration entries to mark the start-point branch as "upstream" from the new branch. It directs link:grgit-pull.html[grgit-pull] without arguments to pull from the upstream when the new branch is checked out.
++
+This behavior is the default when the start point is a remote-tracking branch. Set the `branch.autoSetupMerge` configuration variable to `false` if you want link:grgit-checkout.html[grgit-checkout] and `grgit-branch` to always behave as if `no-track` were given. Set it to `always` if you want this behavior when the start-point is either a local or remote-tracking branch.
+`no-track`:::: Do not set up "upstream" configuration, even if the branch.autoSetupMerge configuration variable is true.
+
+=== remove
+
+names:: (`List<Object>`, default `[]`) Names of the branches. For a more complete list of acceptable inputs, see link:grgit-resolve.html[grgit-resolve] (specifically the `toBranchName` method).
+force:: (`boolean`, default `false`) Set to `true` to allow deleting branches that are not merged into another branch already.
+
+== Examples
+
+To add a branch starting at the current HEAD.
+
+[source, groovy]
+----
+grgit.branch.add(name: 'new-branch')
+----
+
+To add a branch starting at, but not tracking, a local start point.
+
+[source, groovy]
+----
+grgit.branch.add(name: 'new-branch', startPoint: 'local-branch')
+grgit.branch.add(name: 'new-branch', startPoint: 'local-branch', mode: BranchAddOp.Mode.NO_TRACK)
+----
+
+To add a branch starting at and tracking a local start point.
+
+[source, groovy]
+----
+grgit.branch.add(name: 'new-branch', startPoint: 'local-branch', mode: BranchAddOp.Mode.TRACK)
+----
+
+To add a branch starting from and tracking a remote branch.
+
+[source, groovy]
+----
+grgit.branch.add(name: 'new-branch', startPoint: 'origin/remote-branch')
+grgit.branch.add(name: 'new-branch', startPoint: 'origin/remote-branch', mode: BranchAddOp.Mode.TRACK)
+----
+
+To add a branch starting from, but not tracking, a remote branch.
+
+[source, groovy]
+----
+grgit.branch.add(name: 'new-branch', startPoint: 'origin/remote-branch', mode: BranchAddOp.Mode.NO_TRACK)
+----
+
+To change the branch to start at, but not track, a local start point.
+
+[source, groovy]
+----
+grgit.branch.change(name: 'existing-branch', startPoint: 'local-branch')
+grgit.branch.change(name: 'existing-branch', startPoint: 'local-branch', mode: BranchChangeOp.Mode.NO_TRACK)
+----
+
+To change the branch to start at and track a local start point.
+
+[source, groovy]
+----
+grgit.branch.change(name: 'existing-branch', startPoint: 'local-branch', mode: BranchChangeOp.Mode.TRACK)
+----
+
+To change the branch to start from and track a remote start point.
+
+[source, groovy]
+----
+grgit.branch.change(name: 'existing-branch', startPoint: 'origin/remote-branch')
+grgit.branch.change(name: 'existing-branch', startPoint: 'origin/remote-branch', mode: BranchChangeOp.Mode.TRACK)
+----
+
+To change the branch to start from, but not track, a remote start point.
+
+[source, groovy]
+----
+grgit.branch.change(name: 'existing-branch', startPoint: 'origin/remote-branch', mode: BranchChangeOp.Mode.NO_TRACK)
+----
+
+Remove branches that have been merged.
+
+[source, groovy]
+----
+def removedBranches = grgit.branch.remove(names: ['the-branch'])
+def removedBranches = grgit.branch.remove(names: ['the-branch', 'other-branch'], force: false)
+----
+
+Remove branches, even if they haven't been merged.
+
+[source, groovy]
+----
+def removedBranches = grgit.branch.remove(names: ['the-branch'], force: true)
+----
+
+To list local branches only.
+
+[source, groovy]
+----
+def branches = grgit.branch.list()
+def branches = grgit.branch.list(mode: BranchListOp.Mode.LOCAL)
+----
+
+To list remote branches only.
+
+[source, groovy]
+----
+def branches = grgit.branch.list(mode: BranchListOp.Mode.REMOTE)
+----
+
+To list all branches.
+
+[source, groovy]
+----
+def branches = grgit.branch.list(mode: BranchListOp.Mode.ALL)
+----
+
+To list all branches contains specified commit
+
+[source, groovy]
+----
+def branches = grgit.branch.list(contains: %Commit hash or tag name%)
+----
+
+== See Also
+
+- link:https://git-scm.com/docs/git-branch[git-branch]
+- link:grgit-push.html[grgit-push]
+- link:grgit-pull.html[grgit-pull]