Git Integration Functional Specification

Repository Setup, Initialization and Cloning Tasks

Setup

Covers the Setup (Config Files) usecase.

git config [--system | --global | --file] ... 

List, create, edit, and remove entries in a git config file

The IDE suggests some typical variables e. g. user.name, user.email, remote.<name>.url etc.

The IDE detects user mistakes and ideally hints him on allowed values formats etc. - e.g. url ...

Init

Covers the Repository Init usecase.

cd $folder
git init

Create a new repository in a selected folder.

Clone

Covers the Repository Clone usecase.

git clone <repository> <directory>

Clone a local or remote repository.

The IDE detects command failures caused by network connection or invalid authentification and suggests retrying (with modified password, proxy, ...) or let's the user cancel the action.

The IDE automatically detects cloned NetBeans project(s) or guides through new project(s) setup from cloned sources.

The IDE recognizes existing (externally) cloned sources (working trees).

Project private structures are automatically set as ignored.

Supported url schemas are:

• rsync:
• http(s):
• git:
• ssh:
• file:

The IDE proxy settings are used, no additional proxy configuration is needed.

Standard Workflow Tasks

Covered usecases:

• Add
• Commit
• Add or Exclude to or from commit
• Ignore
• View Modifications (Show Changes)
• Quick overview of file status in IDE
• Reset Changes
• Reset
• Revert Changes (Revert previous commits)

git commit -a -F <file> -m <msg> <file>...
git commit --amend ???

git add <filepattern>

git status

git reset [--mixed] [--soft] [--hard] <commit>
git reset [<commit>] [--] <paths>...

git revert [-n] <commit>

• The IDE listens on file events and reflects them in a corresponding git command - e.g git rm
• The IDE recognizes "ignorable" files (e.g. nb project private) and automatically sets them as ignored
• The IDE provides a infrastructure to hook before or after a commit:
  • bugtracking integration
  • unit tests
  • ...

Diff Tasks

Covered usecases:

• Inline Diff
• Diff
• Export uncommited changes (Local changes)
• Export commits (Previous commits)

git diff <commit>..<commit> [--] [<path>...]
git diff <commit>...<commit> [--] [<path>...]
git show $rev:$file

Provide information about changes between:

• files in working tree and a specific commit or index
• two different commits, branches etc.

TODO: how should be handled files already staged in the index - see also Index vs Working Tree

Source Archaeology Tasks

Covered usecases:

• Search history of files
• Blame
• Show History View

git blame [-M] [-C] [-l] [-p] [rev] file
git log [-M] [-C] [-S...] [--follow] ...    
git diff <commit>..<commit> <path>

check also

git-rev-list ...

The IDE provides a Blame action which shows in a files editor for each line information from the commit which introduced the line. Furthermore the annotation sidebar in the editor comes with additional actions:

• to diff the relevant revision with the previous
• to rollback changes created in the selected revision
• to blame the file in the selected revision
• TODO - evaluate 'blame_usage' together with git log ...

The IDE provides a history view which makes it possible to search for commit logs depending on selected context and additional parameters - author, message, date, commit, ... . Basic and also more detailed log information are shown (revision, message, changed files, ...). Various actions are available on revision or file scope:

• diff to previous revision
• revert
• view
• blame
• export diff file

TODO what about a history browser aka gitk?

Branching and Merging Tasks

Tags

Covered usecases:

• Create Tag
• Manage Tags
• Checkout

The IDE provides a way to create lightweight tags or tag objects, list and eventually delete them.

TODO - also signed tags?

TODO - only for commits or all objects?

git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] <name> [<commit>]
git tag -d <name>...
git tag -l -n<num>

Stash

Covered usecases:

• Save Stash
• Manage Stash

The IDE provides a way to create, apply, list, delete and clear a git stashes.

The IDE will provide a built-in visual tool to resolve conflicting files created by applied stash.

git stash list [<options>]
git stash (show | drop | pop ) [<stash>]
git stash apply [--index] [<stash>]
git stash [save [--keep-index] [<message>]]
git stash clear
git stash create

Branches

Covered usecases:

• Checkout
• Create Branch
• Switch to branch
• Merge from Branch
• Rebase Branch
• Cherrypick from Branch

git checkout -b <new-branch>
git checkout <branch>

git branch 

git branch [-a] [(--merged | --no-merged | --contains) [<commit>]]
git branch (-m | -M) [<oldbranch>] <newbranch>
git branch (-d | -D) [-r] <branchname>...

git merge [--no-commit] [-m <msg>] <remote>

git rebase <upstream>

git cherry <upstream> [<head>]
git cherry-pick <commit>

The IDE makes it possible to create, switch to and delete branches.

The IDE makes it possible to merge from branches, rebase a branch or to cherry-pick commits from a branch.

The IDE tracks already merged commits via git cherry

The IDE provides a built-in visual tool to resolve conflicting files created by a merge or cherry-pick.

TODO preview ?

Create and Apply patches

Covered usecases:

• Export uncommited changes (Local changes)
• Export commits (Previous commits)
• Apply Patch

git diff <commit>..<commit> <path>

git apply [<patch>...]

The IDE creates patch files based on the git diff as well as the IDEs built-in diff algorithm and provides a way to either store them as a file or to attach them in a supported bugtracking system.

The IDE is able to apply patch files created by the git algorithm and provides a visual merge tool if needed.

Distributed Workflow

Covered usecases:

• Pull
• Fetch
• Push
• Synchronize

git fetch <repository> <refspec>...
git pull <repository> <refspec>...
git push [--dry-run] [<repository> <refspec>...]

git log origin..HEAD
git log HEAD..origin
git diff origin..HEAD
git diff HEAD..origin

The IDE makes it possible to pull, fetch or push changes from or to a remote or local branch. A default pull, push and fetch will be given by the remote settings:

• a remote in the git configuration file: $GIT_DIR/config,
• a file in the $GIT_DIR/remotes directory, or
• a file in the $GIT_DIR/branches directory.

The IDE will assist with a list of possible choices in case there is more then one remote specified.

The IDE provides a view to inspect differences between local and tracked remote branches.

TODO The IDE makes it possible to inspect remote repositories for references (heads, tags).

git ls-remote [--heads] [--tags]  <repository> <refs>...

Supported url schemas are:

• rsync:
• http(s):
• git:
• ssh:
• file:

The IDE proxy settings are used, no additional proxy configuration is needed.

Covered git commands

• config
• init
• clone

• add
• rm
• mv
• commit
• reset
• revert
• tag
• status

• diff
• blame/annotate
• log (see also git-rev-list)
• show
• show-branch

• branch
• stash
• merge
• cherry
• cherry-pick
• rebase
• checkout

• pull
• fetch
• push
• ls-remote

• diff
• format-patch
• apply

Covered Git Files

• ignore - .gitignore, $GIT_DIR/info/exclude
• config - ~/.gitconfig), $(prefix)/etc/gitconfig, $GIT_DIR/config