Description
Issue to track API consistency as discussed in #265.
Below is @nulltoken's original writeup / chart
Below a proposal for an exhaustive ruleset regarding this. Please review it carefully as I may have had made mistakes:
Staging deals with moving the state of a file from the Working Directory toward the Index
Stage | File exists in Index | File exists in WD | Ignore unmatched pathspec | Result |
---|---|---|---|---|
01 | Y | Y | Y | Version in Index is replaced with version in Workdir |
02 | Y | Y | Version in Index is created from version in Workdir | |
03 | Y | Y | Version in Index is removed | |
04 | Y | Does nothing | ||
05 | Y | Y | Version in Index is replaced with version in Workdir | |
06 | Y | Version in Index is created from version in Workdir | ||
07 | Y | Version in Index is removed | ||
08 | Throws |
Unstaging deals with moving the state of a file from the Head toward the Index. If the Head is orphaned (ie. the current Head "contains" no commit), then the file will be considered as "non existing is the Head"
Unstage | File exists in Index | File exists in Head | Ignore unmatched pathspec | Result |
---|---|---|---|---|
01 | Y | Y | Y | Version in Index is replaced with version in Head |
02 | Y | Y | Version in Index is removed | |
03 | Y | Y | Version in Index is replaced with version in Head | |
04 | Y | Does nothing | ||
05 | Y | Y | Version in Index is replaced with version in Head | |
06 | Y | Version in Index is removed | ||
07 | Y | Version in Index is replaced with version in Head | ||
08 | Throws |
Removing deals with clearing an entry from the Index and, optionally, from the Working Directory as well
Remove | File exists in Index | File exists in WD | Ignore unmatched pathspec | Remove from WD as well | Result |
---|---|---|---|---|---|
01 | Y | Y | Y | Y | Both entries are removed from Index and Workdir |
02 | Y | Y | Y | Entry in Index is Removed | |
03 | Y | Y | Y | ??? | |
04 | Y | Y | Does nothing | ||
05 | Y | Y | Y | Entry in Index is removed | |
06 | Y | Y | Entry in Index is removed | ||
07 | Y | Y | ??? | ||
08 | Y | Does Nothing | |||
09 | Y | Y | Y | Both entries are removed from Index and Workdir | |
10 | Y | Y | ??? | ||
11 | Y | Y | Throws | ||
12 | Y | Throws | |||
13 | Y | Y | Entry in Index is removed | ||
14 | Y | Entry in Index is removed | |||
15 | Y | Throws | |||
16 | Throws |
Note: I haven't dealt with Move
which is slightly more complicated. I'd rather make sure the behavior Remove
is settled first.