Git notes

ObjectiveGit/GTNote.h

@@ -0,0 +1,63 @@
+//
+//  GTNote.h
+//  ObjectiveGitFramework
+//
+//  Created by Slava Karpenko on 5/16/2016.
+//
+//  The MIT License
+//
+//  Copyright (c) 2016 Wildbit LLC
+//
+//  Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to deal
+//  in the Software without restriction, including without limitation the rights
+//  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+//  copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+//  The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+//  THE SOFTWARE.
+//
+
+#import <Foundation/Foundation.h>
+#import "git2/oid.h"
+
+@class GTSignature;
+@class GTRepository;
+@class GTOID;
+@class GTObject;
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface GTNote : NSObject {}
+
+/// The author of the note.
+@property (nonatomic, readonly, strong, nullable) GTSignature *author;
+
+/// The committer of the note.
+@property (nonatomic, readonly, strong, nullable) GTSignature *committer;
+
+/// Content of the note.
+@property (nonatomic, readonly, strong) NSString *note;
+
+@property (nonatomic, readonly, strong) GTObject *target;
+
+/// The underlying `git_note` object.
+- (git_note * _Nullable)git_note __attribute__((objc_returns_inner_pointer));
+
+/// These initializers may fail if there's no note attached to the provided oid.
+- (nullable instancetype)initWithTargetOID:(GTOID*)oid repository:(GTRepository*)repository ref:(nullable NSString*)ref;
+- (nullable instancetype)initWithTargetGitOID:(git_oid*)oid repository:(git_repository *)repository ref:(const char* _Nullable)ref;
+
+@end
+
+NS_ASSUME_NONNULL_END
+

ObjectiveGit/GTNote.m

@@ -0,0 +1,75 @@
+//
+//  GTNote.m
+//  ObjectiveGitFramework
+//
+//  Created by Slava Karpenko on 16.05.16.
+//  Copyright © 2016 Wildbit LLC. All rights reserved.
+//
+
+#import "GTNote.h"
+#import "NSError+Git.h"
+#import "GTSignature.h"
+#import "GTReference.h"
+#import "GTRepository.h"
+#import "NSString+Git.h"
+#import "GTOID.h"
+
+#import "git2/errors.h"
+#import "git2/notes.h"
+
+@interface GTNote ()
+{
+	git_note *_note;
+}
+
+@end
+@implementation GTNote
+
+- (NSString *)description {
+	return [NSString stringWithFormat:@"<%@: %p>", NSStringFromClass([self class]), self];
+}
+
+#pragma mark API
+
+- (void)dealloc {
+	if (_note != NULL) {
+		git_note_free(_note);
+	}
+}
+
+- (git_note *)git_note {
+	return _note;
+}
+
+- (NSString*)note {
+	return @(git_note_message(self.git_note));
+}
+
+- (GTSignature *)author {
+	return [[GTSignature alloc] initWithGitSignature:git_note_author(self.git_note)];
+}
+
+- (GTSignature *)committer {
+	return [[GTSignature alloc] initWithGitSignature:git_note_committer(self.git_note)];
+}
+
+- (GTOID*)targetOID {
+	return [GTOID oidWithGitOid:git_note_id(self.git_note)];
+}
+
+- (instancetype)initWithTargetOID:(GTOID*)oid repository:(GTRepository*)repository ref:(NSString*)ref {
+	return [self initWithTargetGitOID:(git_oid *)oid.git_oid repository:repository.git_repository ref:ref.UTF8String];
+}
+
+- (instancetype)initWithTargetGitOID:(git_oid*)oid repository:(git_repository *)repository ref:(const char*)ref {
+	if (self = [super init]) {
+		int gitErr = git_note_read(&_note, repository, ref, oid);
+
+		if (gitErr != GIT_OK)
+			return nil;		// Cannot read the note, means it either doesn't exists for this object, this object is not found, or whatever else.
+	}
+
+	return self;
+}
+
+@end

ObjectiveGit/GTRepository+RemoteOperations.h

@@ -97,6 +97,20 @@ typedef NS_ENUM(NSInteger, GTFetchPruneOption) {
 /// will point to an error describing what happened).
 - (BOOL)pushBranches:(NSArray<GTBranch *> *)branches toRemote:(GTRemote *)remote withOptions:(nullable NSDictionary *)options error:(NSError **)error progress:(nullable void (^)(unsigned int current, unsigned int total, size_t bytes, BOOL *stop))progressBlock;
 
+/// Push a given Git notes reference name to a remote.
+///
+/// noteRef       - Name of the notes reference. If NULL, will default to whatever the default is (e.g. "refs/notes/commits")
+/// remote        - The remote to push to. Must not be nil.
+/// options       - Options applied to the push operation. Can be NULL.
+///                 Recognized options are:
+///                 `GTRepositoryRemoteOptionsCredentialProvider`
+/// error         - The error if one occurred. Can be NULL.
+/// progressBlock - An optional callback for monitoring progress. May be NULL.
+///
+/// Returns YES if the push was successful, NO otherwise (and `error`, if provided,
+/// will point to an error describing what happened).
+- (BOOL)pushNotes:(nullable NSString *)noteRef toRemote:(GTRemote *)remote withOptions:(nullable NSDictionary *)options error:(NSError **)error progress:(nullable void (^)(unsigned int current, unsigned int total, size_t bytes, BOOL *stop))progressBlock;
+
 /// Delete a remote branch
 ///
 /// branch        - The branch to push. Must not be nil.

ObjectiveGit/GTRepository+RemoteOperations.m

@@ -21,6 +21,8 @@
 
 #import "git2/errors.h"
 #import "git2/remote.h"
+#import "git2/notes.h"
+#import "git2/buffer.h"
 
 NSString *const GTRepositoryRemoteOptionsCredentialProvider = @"GTRepositoryRemoteOptionsCredentialProvider";
 NSString *const GTRepositoryRemoteOptionsFetchPrune = @"GTRepositoryRemoteOptionsFetchPrune";
@@ -198,6 +200,28 @@ - (BOOL)pushBranches:(NSArray *)branches toRemote:(GTRemote *)remote withOptions
 	return [self pushRefspecs:refspecs toRemote:remote withOptions:options error:error progress:progressBlock];
 }
 
+- (BOOL)pushNotes:(NSString *)noteRef toRemote:(GTRemote *)remote withOptions:(NSDictionary *)options error:(NSError **)error progress:(GTRemotePushTransferProgressBlock)progressBlock {
+	NSParameterAssert(remote != nil);
+
+	if (noteRef == nil) {
+		git_buf default_ref_name = { 0 };
+		int gitErr = git_note_default_ref(&default_ref_name, self.git_repository);
+		if (gitErr != GIT_OK) {
+			git_buf_free(&default_ref_name);
+
+			if (error != NULL) {
+				*error = [NSError git_errorFor:gitErr description:@"Unable to get default git notes reference name"];
+			}
+
+			return NO;
+		}
+
+		noteRef = [NSString stringWithUTF8String:default_ref_name.ptr];
+	}
+
+	return [self pushRefspecs:@[[NSString stringWithFormat:@"%@:%@", noteRef, noteRef]] toRemote:remote withOptions:options error:error progress:progressBlock];
+}
+
 #pragma mark - Deletion (Public)
 - (BOOL)deleteBranch:(GTBranch *)branch fromRemote:(GTRemote *)remote withOptions:(NSDictionary *)options error:(NSError **)error {
 	NSParameterAssert(branch != nil);

ObjectiveGit/GTRepository.h

@@ -51,6 +51,7 @@
 @class GTTag;
 @class GTTree;
 @class GTRemote;
+@class GTNote;
 
 NS_ASSUME_NONNULL_BEGIN
 
@@ -604,6 +605,48 @@ typedef NS_ENUM(NSInteger, GTRepositoryStateType) {
 /// Returns YES if operation was successful, NO otherwise
 - (BOOL)cleanupStateWithError:(NSError **)error;
 
+/// Creates a new note in this repo (using a default notes reference, e.g. "refs/notes/commits")
+///
+/// note      - Note text.
+/// theTarget - Object (usually a commit) to which this note attaches to.
+///             This object must belong to this repository.
+/// ref       - Name for the notes reference in the repo, or nil for default ("refs/notes/commits")
+/// author    - Signature of the author for this note, and
+///             of the note creation time
+/// committer - Signature of the committer for this note.
+/// overwrite - If set to YES, the note will be overwritten if it already exists.
+/// error     - Will be filled with a NSError object in case of error.
+///             May be NULL.
+///
+/// Returns the newly created note or nil on error.
+- (nullable GTNote *)createNote:(NSString *)note target:(GTObject *)theTarget ref:(nullable NSString *)ref author:(GTSignature *)author committer:(GTSignature *)committer overwriteIfExists:(BOOL)overwrite error:(NSError **)error;
+
+/// Removes a note attached to object in this repo (using a default notes reference, e.g. "refs/notes/commits")
+///
+/// parentObject - Object (usually a commit) to which the note to be removed is attached to.
+///                This object must belong to this repository.
+/// ref          - Name for the notes reference in the repo, or nil for default ("refs/notes/commits")
+/// author       - Signature of the author for this note removal, and
+///                of the note removal time
+/// committer    - Signature of the committer for this note removal.
+/// error        - Will be filled with a NSError object in case of error.
+///                May be NULL.
+///
+/// Returns the YES on success and NO on error.
+- (BOOL)removeNoteFromObject:(GTObject *)parentObject ref:(nullable NSString *)ref author:(GTSignature *)author committer:(GTSignature *)committer error:(NSError **)error;
+
+/// Enumerates through all stored notes in this repo (using a default notes reference, e.g. "refs/notes/commits")
+///
+/// error     - Will be filled with a NSError object in case of error.
+///             May be null.
+/// ref       - Name for the notes reference in the repo, or nil for default ("refs/notes/commits")
+/// block     - A block to be called on each encountered note object. The block accepts
+///             a reference to `note`, an `object` that is annotated with the note.
+///             If the block sets `stop` to YES, the iterator is finished.
+///
+/// Returns YES on overall success or NO on error of any kind.
+- (BOOL)enumerateNotesWithError:(NSError **)error ref:(nullable NSString *)ref usingBlock:(void (^)(GTNote *note, GTObject *object, BOOL *stop))block;
+
 @end
 
 NS_ASSUME_NONNULL_END

ObjectiveGit/GTRepository.m

@@ -52,6 +52,7 @@
 #import "NSError+Git.h"
 #import "NSString+Git.h"
 #import "GTRepository+References.h"
+#import "GTNote.h"
 
 #import "git2.h"
 
@@ -919,4 +920,76 @@ - (BOOL)cleanupStateWithError:(NSError * _Nullable __autoreleasing *)error {
 	return YES;
 }
 
+#pragma mark Notes
+
+- (GTNote *)createNote:(NSString *)note target:(GTObject *)theTarget ref:(NSString *)ref author:(GTSignature *)author committer:(GTSignature *)committer overwriteIfExists:(BOOL)overwrite error:(NSError **)error {
+	git_oid oid;
+
+	int gitError = git_note_create(&oid, self.git_repository, ref.UTF8String, author.git_signature, committer.git_signature, theTarget.OID.git_oid, [note UTF8String], overwrite ? 1 : 0);
+	if (gitError != GIT_OK) {
+		if (error != NULL) *error = [NSError git_errorFor:gitError description:@"Failed to create a note in repository"];
+
+		return nil;
+	}
+
+	return [[GTNote alloc] initWithTargetOID:theTarget.OID repository:self ref:ref];
+}
+
+- (BOOL)removeNoteFromObject:(GTObject *)parentObject ref:(NSString *)ref author:(GTSignature *)author committer:(GTSignature *)committer error:(NSError **)error {
+	int gitError = git_note_remove(self.git_repository, ref.UTF8String, author.git_signature, committer.git_signature, parentObject.OID.git_oid);
+	if (gitError != GIT_OK) {
+		if(error != NULL) *error = [NSError git_errorFor:gitError description:@"Failed to delete note from %@", parentObject];
+		return NO;
+	}
+
+	return YES;
+}
+
+- (BOOL)enumerateNotesWithError:(NSError **)error ref:(NSString *)ref usingBlock:(void (^)(GTNote *note, GTObject *object, BOOL *stop))block
+{
+	git_note_iterator* iter = NULL;
+
+	int gitError = git_note_iterator_new(&iter, self.git_repository, ref.UTF8String);
+
+	if (gitError != GIT_OK)
+	{
+		if(error != NULL) *error = [NSError git_errorFor:gitError description:@"Failed to enumerate notes"];
+		return NO;
+	}
+
+	git_oid note_id;
+	git_oid object_id;
+	BOOL success = YES;
+
+	while (git_note_next(&note_id, &object_id, iter) == GIT_OK) {
+		NSError* lookupErr = nil;
+
+		GTNote* note = 	[[GTNote alloc] initWithTargetGitOID:&object_id repository:self.git_repository ref:ref.UTF8String];
+		if (note == nil) {
+			if (error != NULL)
+				*error = [NSError git_errorFor:GIT_ENOTFOUND description:@"Cannot create note"];
+			success = NO;
+			break;
+		}
+
+		GTObject* obj = [self lookUpObjectByGitOid:&object_id error:&lookupErr];
+		if (obj == nil && lookupErr != nil) {
+			if (error != NULL)
+				*error = lookupErr;
+			success = NO;
+			break;
+		}
+
+		BOOL stop = NO;
+		block(note, obj, &stop);
+		if (stop) {
+			break;
+		}
+	}
+
+	git_note_iterator_free(iter);
+
+	return success;
+}
+
 @end

ObjectiveGit/ObjectiveGit.h

@@ -70,6 +70,7 @@ FOUNDATION_EXPORT const unsigned char ObjectiveGitVersionString[];
 #import <ObjectiveGit/GTFilterList.h>
 #import <ObjectiveGit/GTFilterSource.h>
 #import <ObjectiveGit/GTFetchHeadEntry.h>
+#import <ObjectiveGit/GTNote.h>
 
 #import <ObjectiveGit/GTObjectDatabase.h>
 #import <ObjectiveGit/GTOdbObject.h>