Git: Partial staging
Staging area (index) is a place where you prepare the next commit. This area contains candidate files for going into the local repository. At the end all the content from here will be committed as an assembly into the local repository.
A commit should be the smallest amount of work that represents a cohesive feature in a build-able state. Sometimes basic staging of files with git add . cannot fulfill this requirement as it will add all the changes to staging area. To stage a subset of eligible files at a time, excluding those which are not ready, one can use git add <file> or git add *.properties .
Git also offers a possibility to stage finer-grained changes by adding certain parts of files and not the rest.To have it done this way a command git add -p is there to help (note that p here is shorthand from patch).
By using this command git will break down changes into one or more separate "hunks". A hunk is a small, meaningful set of lines separated from other hunks by unchanged part of file.
Through git interface users will be asked which files they would like to partially stage; then, for each section of the selected files, it will display hunks of the file diff and ask if you would like to stage them, one by one.
There are several different available subcommands. Here is the complete list with short explanation:
y - stage this hunk
n - do not stage this hunk
q - quit; do not stage this hunk or any of the remaining ones
a - stage this hunk and all later hunks in the file
d - do not stage this hunk or any of the later hunks in the file
g - select a hunk to go to
/ - search for a hunk matching the given regex
j - leave this hunk undecided, see next undecided hunk
J - leave this hunk undecided, see next hunk
k - leave this hunk undecided, see previous undecided hunk
K - leave this hunk undecided, see previous hunk
s - split the current hunk into smaller hunks
e - manually edit the current hunk
? - print helpThe most interesting subcommands here are e and s, which allow the user to manually do the desired work.
Manually editing hunks is immensely powerful, but also a bit complicated and it is not recommended for beginners. The most important thing to keep in mind: every diff is always indented with one character in addition to whatever other indentation is there. This character can either be a space (indicates an unchanged line), a - (indicates removed line), or a + (indicates added line). Nothing else. It must be either a space, a - or a +.
It is very easy to make a mistake here. When this happens the patch will not apply. After you exit editor you will see a message like: "Your edited hunk does not apply. Edit again (saying "no" discards!) [y/n]?". In addition the message may be accompanied by "fatal: corrupt patch at line <XXX>". This means that some change made in the editor caused the patch not to be able to merge into the rest of the file.
When you are done with staging, then you can continue with:
git diff --stagedto check that you staged the correct changesgit reset -pto unstage mistakenly added hunksgit commit -vto view your commit while you edit the commit message.
