NetBeans Git Support Use Case Specification

Describes the use cases for the NetBeans Git integration. See also the functional specification and UI specification for addional information.

... work in progress ...

_

_

Setup (Config Files)

Actor: User

Action: User wants to create or edit git configuration files

"Priority:" 2

Scenario:

• User invokes 'config' either from the main menu or context menu
• User is able to edit the global (~/.gitconfig), system ($(prefix)/etc/gitconfig) or repository specific ($GIT_DIR/config) git config file

TODO do we want to allow edit global and system config or only the config from a repository

Repository Init

Actor: User

Action: User wants to create a new git repository

"Priority:" 1

Scenario:

• User selects an not yet versioned folder and invokes 'init' either from the main menu or context menu
• The selected folder becomes a new git repository

Repository Clone

Actor: User

Action: User wants to clone a git repository

"Priority:" 1

Scenario 1 - clone from url:

• User invokes 'clone' from the main menu
• The user specifies the url, local folder and additional clone options
• The repository gets cloned

Scenario 2 - clone selected repository: TODO: not sure about this one - does anybody find it useful at all?

• User selects a git repository and invokes 'clone' from the main menu
• The user specifies the local folder to clone into and additional clone options
• The repository gets cloned

Add

Actor: User

Action: User wants to add some files to version control or to stage them on index

"Priority:" 1

Scenario:

• User selects a versioned context and invokes 'add' either from the main menu or context menu
• Files are added (recursively id needed)

Commit

Actor: User

Action: User wants to commit some files

"Priority:" 1

Scenario:

• User selects a versioned context and invokes 'commit' either from the main menu or context menu
• The user is presented with a list of to be committed files.
• User may fine-tune the list
• User is prompted for a commit message
• User may specify additional commit options
• Files are committed

Add or Exclude to or from commit

Actor: User

Action: User wants to include/exclude some files into/from future commits

"Priority:" 1

Scenario:

• User selects a versioned context and invokes 'add/exclude from commit' from the main menu or context menu
• Selected files are Added/Excluded to/from the index - they will/won't be taken in acount by commit
• (TODO) decide about the default action - added by default with an later optional exclude, or must be explicitly added/excluded by user. See also Open Issues/misc/Index vs working tree

Ignore

Actor: User

Action: User wants to ignore some files

"Priority:" 1

Scenario:

• User selects a not yet added and versioned context in a git repository and invokes 'ignore' from the main menu or context menu
• Selected files are set as 'Ignored' - they won't be taken in acount by commit. It's possible to unignore them eventually.

Reset Changes (Revert local changes)

Actor: User

Action: User wants to throw away local changes made to selected files and replace those files with the ones in the index/head

"Priority:" 1

Scenario:

• User selects a versioned context and invokes 'Reset Changes' from the main menu or context menu
• Dialog pops up asking for additional reset options
• Selected files are replaced with those in index

Reset

Actor: User

Action: User wants to reset the HEAD to a specified state

"Priority:" 2

Scenario:

• User selects a versioned context and invokes 'Reset' from the main menu or context menu
• Dialog pops up asking for additional reset options
• Specified changes are applied

Revert Changes (Revert previous commits)

Actor: User

Action: User wants to revert previous commits

"Priority:" 2

Scenario:

• User selects a versioned context and invokes 'revert' from the main menu
• Dialog pops up asking for additional revert options - revisions etc.
• A new revision is created which reverts the previous commits
• TODO revert only in working tree

View Modifications (Show Changes)

Actor: User

Action: Show list of files that are modified or new

"Priority:" 1

Scenario:

• User selects a versioned context and invokes Show Changes either from the main menu or context menu
• All files which are modified/new/deleted are listed in a special Git View
• TODO - index vs working tree?

Quick overview of file status in IDE

Actor: User

Action: Annotate git status information in the IDE (nodes in Explorer views, Editor tabs, etc.)

"Priority:" 1

Scenario:

• No explicit actions required
• Most important status (modified, new, ...) is color coded in node labels
• Additional git specific file information is show via versioning badges on files and folders

Inline diff - show local modifications in a files sidebar

Actor: User

Action: Show the inline diff of a file in the editor

"Priority:" 1

Scenario:

• No explicit action is required
• Diff editor sidebar shows local modifications made to the file
• TODO show also differences between working tree and index?

Diff - view local modifications

Actor: User

Action: Show the editable diff view for a file

"Priority:" 1

Scenario:

• User selects a versioned context and invokes 'diff' either from the main menu or context menu
• Modified files from the selected context are shown in the Diff view
• TODO show also differences between working tree and index? See also Open Issues/misc/Index vs working tree

Export uncommited changes (Local changes)

Actor: User

Action: Export local changes

"Priority:" 1

Scenario:

• User selects a versioned context and invokes 'export uncommited changes' either from the main menu or context menu
• User specifies the patch files name and location
• A patch file is created containing differences between the working tree and the last commit
• TODO also differences between working tree and index, or index and last commit? See also Open Issues/misc/Index vs working tree

Export commits (Previous commits)

Actor: User

Action: Export some previous commits

"Priority:" 2

Scenario:

• User selects a versioned context and invokes 'export commits' either from the main menu or context menu
• User specifies the patch files name and location
• A patch file is created containing differences between specified commits

Apply Patch

Actor: User

Action: Apply a git patch file

"Priority:" 1

Scenario:

• User selects a versioned context and invokes 'Apply' either from the main menu or context menu
• User specifies a patch files location etc.
• The patch file is applied either on the working tree or TODO also on index

Search history of files

Actor: User

Action: User wants to show/search the history for a file or a group of files

"Priority:" 1

Scenario:

• User selects a versioned context and invokes Search History from the main menu or context menu
• The search history view will be opened

Blame

Actor: User

Action: Show Blame sidebar in the editor

"Priority:" 1

Scenario:

• User selects some versioned files and invokes 'blame' from the main menu or context menu
• The relevant files are opened in editor and git blame/annotations are shown beside each line

Create Tag

Actor: User

Action: User wants to tag a commit

"Priority:" 2

Scenario:

• User selects a versioned context and invokes 'Tags' from the main menu or context menu
• User specifies the tag name, revision and additional options - e.g lightweight, message, ...
• A tag will be created in the selected repository

Manage Tags

Actor: User

Action: User wants to manage tags

"Priority:" 2

Scenario:

• User selects a versioned context and invokes 'manage tags' from the main menu
• User is presented with a list of tags and is able to inspect and delete them

Checkout

Actor: User

Action: User wants to checkout a specific revision/tag/branch

"Priority:" 1

Scenario:

• User selects a a versioned context and invokes 'chekout' from the main menu
• User specifies the revision/tag/branch to checkout
• The working tree will be switched to the specified revision

Create Branch

Actor: User

Action: User wants to create a branch

"Priority:" 1

Scenario:

• User selects a versioned context and invokes 'create branch' from the main menu
• User specifies the new branch name and revision
• The branch is created

Switch to Branch

Actor: User

Action: User wants to switch to a branch (see also Checkout)

"Priority:" 1

Scenario:

• User selects a versioned context and invokes 'switch branch' from the main menu
• User specifies the branch and additional options - keep local changes etc.
• The working tree is switched to the specified branch

Merge from Branch

Actor: User

Action: User wants to merge from another branch

"Priority:" 1

Scenario:

• User selects a versioned context and invokes 'merge' from the main menu
• User specifies the branch he wants to merge from a additional merge options - e.g. no-commit, msg, ...
• Changes from another branch are merged

Cherrypick from Branch

Actor: User

Action: User wants to merge some commits from a branch

"Priority:" 2

Scenario:

• User selects a versioned context and invokes 'cherry pick' from the main menu
• User specifies the branchcommits to be merged and additional options - e.g. --no-commit
• Changes from another branch are merged

Remove Branch

Actor: User

Action: User wants to remove a branch

"Priority:" 2

Scenario:

• User selects a a versioned context and invokes 'merge' from the main menu
• User specifies the branch he wants to remove
• Branch will be removed

Save Stash

Actor: User

Action: User wants to stash his local changes

"Priority:" 2

Scenario:

• User selects a versioned context and invokes 'save stash' from the main menu
• User may specify a stash message and additional options (--keep-index, pop, ...)
• Local changes are stashed

Manage Stash

Actor: User

Action: User wants to manage stored stashes

"Priority:" 2

Scenario:

• User selects a versioned context and invokes 'manage stash' from the main menu
• User is presented with a list of stored stashes and is able to inspect, delete, clear the stored stashes

Rebase Branch (TODO)

Pull

Actor: User

Action: User wants to pull (fetch and merge) from a remote repository

"Priority:" 1

Scenario:

• User selects a versioned context and invokes 'pull' from the main menu
• User specifies the repository and branch to pull from
• The retrieved heads are merged into the current branch

Fetch

Actor: User

Action: User wants to fetch from a remote repository

"Priority:" 1

Scenario:

• User selects a versioned context and invokes 'fetch' from the main menu
• User specifies the repository and branch to fetch from
• The changes are fetched

Push

Actor: User

Action: User wants to update a remote repository from the local

"Priority:" 1

Scenario:

• User selects a a versioned context and invokes 'push' from the main menu
• User specifies the repository to push (or fetch eventually) to
• The remote repository is updated

Synchronize

Actor: User

Action: User wants to see differences in commits between his local and a tracked remote branches

"Priority:" 2

Scenario:

• User selects a a versioned context and invokes 'synchronize' from the main menu
• User specifies the local and the tracked remote branch(es)
• The user is presented with a list of commits