Git Integration Functional Specification
- 1 Git Integration Functional Specification
- 1.1 Repository Setup, Initialization and Cloning Tasks
- 1.2 Standard Workflow Tasks
- 1.3 Diff Tasks
- 1.4 Source Archaeology Tasks
- 1.5 Branching and Merging Tasks
- 1.5.1 Tags
- 1.5.2 Stash
- 1.5.3 Branches
- 1.5.4 Create and Apply patches
- 1.6 Distributed Workflow
- 1.7 Covered git commands
- 1.8 Covered Git Files
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:
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:
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:
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:
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:
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:
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:
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