diff --git a/src/git.coffee b/src/git.coffee index 87e7a77e7..0fd49f0d9 100644 --- a/src/git.coffee +++ b/src/git.coffee @@ -7,20 +7,26 @@ GitUtils = require 'git-utils' # Public: Represents the underlying git operations performed by Atom. # -# Ultimately, this is an overlay to the native [git-utils](https://github.com/atom/node-git) module. +# This class shouldn't be instantiated directly but instead by accessing the +# global project instance and calling `getRepo()`. +# +# ## Example +# +# ```coffeescript +# git = global.project.getRepo() +# console.log git.getOriginUrl() +# ``` module.exports = class Git _.extend @prototype, Subscriber _.extend @prototype, EventEmitter - ### Public ### - # Creates a new `Git` instance. + # Private: Creates a new `Git` instance. # - # path - The git repository to open - # options - A hash with one key: - # refreshOnWindowFocus: A {Boolean} that identifies if the windows should refresh - # - # Returns a new {Git} object. + # * path: The path to the git repository to open + # * options: + # + refreshOnWindowFocus: + # A Boolean that identifies if the windows should refresh @open: (path, options) -> return null unless path try @@ -40,13 +46,12 @@ class Git upstream: null statusTask: null - ### Internal ### - - # Creates a new `Git` object. + # Private: Creates a new `Git` object. # - # path - The {String} representing the path to your git working directory - # options - A hash with the following keys: - # refreshOnWindowFocus: If `true`, {#refreshIndex} and {#refreshStatus} are called on focus + # * path: The {String} representing the path to your git working directory + # * options: + # + refreshOnWindowFocus: If `true`, {#refreshIndex} and {#refreshStatus} + # are called on focus constructor: (path, options={}) -> @repo = GitUtils.open(path) unless @repo? @@ -69,6 +74,7 @@ class Git @subscribe buffer, 'saved', bufferStatusHandler @subscribe buffer, 'reloaded', bufferStatusHandler + # Private: destroy: -> if @statusTask? @statusTask.terminate() @@ -80,35 +86,28 @@ class Git @unsubscribe() - ### Public ### - - # Retrieves the git repository. - # - # Returns a new `Repository`. + # Private: Returns the corresponding {Repository} getRepo: -> unless @repo? throw new Error("Repository has been destroyed") @repo - # Reread the index to update any values that have changed since the last time the index was read. + # Public: Reread the index to update any values that have changed since the + # last time the index was read. refreshIndex: -> @getRepo().refreshIndex() - # Retrieves the path of the repository. - # - # Returns a {String}. + # Public: Returns the path of the repository. getPath: -> @path ?= fsUtils.absolute(@getRepo().getPath()) - # Retrieves the working directory of the repository. - # - # Returns a {String}. + # Public: Returns the working directory of the repository. getWorkingDirectory: -> @getRepo().getWorkingDirectory() - # Retrieves the status of a single path in the repository. + # Public: Returns the status of a single path in the repository. # - # path - An {String} defining a relative path + # * path: A String defining a relative path # - # Returns a {Number}. + # Returns a {Number}, FIXME representing what? getPathStatus: (path) -> currentPathStatus = @statuses[path] ? 0 pathStatus = @getRepo().getStatus(@relativize(path)) ? 0 @@ -120,57 +119,35 @@ class Git @trigger 'status-changed', path, pathStatus pathStatus - # Identifies if a path is ignored. - # - # path - The {String} path to check - # - # Returns a {Boolean}. + # Public: Determines if the given path is ignored. isPathIgnored: (path) -> @getRepo().isIgnored(@relativize(path)) - # Identifies if a value represents a status code. - # - # status - The code {Number} to check - # - # Returns a {Boolean}. + # Public: Determine if the given status indicates modification. isStatusModified: (status) -> @getRepo().isStatusModified(status) - # Identifies if a path was modified. - # - # path - The {String} path to check - # - # Returns a {Boolean}. + # Public: Determine if the given path is modified. isPathModified: (path) -> @isStatusModified(@getPathStatus(path)) - # Identifies if a status code represents a new path. - # - # status - The code {Number} to check - # - # Returns a {Boolean}. + # Public: Determine if the given status indicates a new path. isStatusNew: (status) -> @getRepo().isStatusNew(status) - # Identifies if a path is new. - # - # path - The {String} path to check - # - # Returns a {Boolean}. + # Public: Determine if the given path is new. isPathNew: (path) -> @isStatusNew(@getPathStatus(path)) - # Makes a path relative to the repository's working directory. - # - # path - The {String} path to convert - # - # Returns a {String}. + # Public: Makes a path relative to the repository's working directory. relativize: (path) -> @getRepo().relativize(path) - # Retrieves a shortened version of the HEAD reference value. + # Public: Retrieves a shortened version of the HEAD reference value. # - # This removes the leading segments of `refs/heads`, `refs/tags`, or `refs/remotes`. - # It also shortens the SHA-1 of a detached `HEAD` to 7 characters. + # This removes the leading segments of `refs/heads`, `refs/tags`, or + # `refs/remotes`. It also shortens the SHA-1 of a detached `HEAD` to 7 + # characters. # - # Returns a {String}. + # Returns a String. getShortHead: -> @getRepo().getShortHead() - # Restore the contents of a path in the working directory and index to the version at `HEAD`. + # Public: Restore the contents of a path in the working directory and index + # to the version at `HEAD`. # # This is essentially the same as running: # ``` @@ -178,7 +155,7 @@ class Git # git checkout HEAD -- # ``` # - # path - The {String} path to checkout + # path - The String path to checkout # # Returns a {Boolean} that's `true` if the method was successful. checkoutHead: (path) -> @@ -186,27 +163,32 @@ class Git @getPathStatus(path) if headCheckedOut headCheckedOut - # Retrieves the number of lines added and removed to a path. + # Public: Retrieves the number of lines added and removed to a path. # - # This compares the working directory contents of the path to the `HEAD` version. + # This compares the working directory contents of the path to the `HEAD` + # version. # - # path - The {String} path to check + # * path: + # The String path to check # - # Returns an object with two keys, `added` and `deleted`. These will always be greater than 0. + # Returns an object with two keys, `added` and `deleted`. These will always + # be greater than 0. getDiffStats: (path) -> @getRepo().getDiffStats(@relativize(path)) - # Identifies if a path is a submodule. + # Public: Identifies if a path is a submodule. # - # path - The {String} path to check + # * path: + # The String path to check # # Returns a {Boolean}. isSubmodule: (path) -> @getRepo().isSubmodule(@relativize(path)) - # Retrieves the status of a directory. + # Public: Retrieves the status of a directory. # - # path - The {String} path to check + # * path: + # The String path to check # - # Returns a {Number} representing the status. + # Returns a Number representing the status. getDirectoryStatus: (directoryPath) -> directoryPath = "#{directoryPath}/" directoryStatus = 0 @@ -214,28 +196,37 @@ class Git directoryStatus |= status if path.indexOf(directoryPath) is 0 directoryStatus - # Retrieves the line diffs comparing the `HEAD` version of the given path and the given text. + # Public: Retrieves the line diffs comparing the `HEAD` version of the given + # path and the given text. # - # This is similar to the commit numbers reported by `git status` when a remote tracking branch exists. + # This is similar to the commit numbers reported by `git status` when a + # remote tracking branch exists. # - # path - The {String} path (relative to the repository) - # text - The {String} to compare against the `HEAD` contents + # * path: + # The String path (relative to the repository) + # * text: + # The String to compare against the `HEAD` contents # - # Returns an object with two keys, `ahead` and `behind`. These will always be greater than zero. + # Returns an object with two keys, `ahead` and `behind`. These will always be + # greater than zero. getLineDiffs: (path, text) -> @getRepo().getLineDiffs(@relativize(path), text) + # Public: Returns the git configuration value specified by the key. getConfigValue: (key) -> @getRepo().getConfigValue(key) + # Public: Returns the origin url of the repository. getOriginUrl: -> @getConfigValue('remote.origin.url') + # Public: ? getReferenceTarget: (reference) -> @getRepo().getReferenceTarget(reference) + # Public: ? getAheadBehindCount: (reference) -> @getRepo().getAheadBehindCount(reference) + # Public: ? hasBranch: (branch) -> @getReferenceTarget("refs/heads/#{branch}")? - ### Internal ### - + # Private: refreshStatus: -> @statusTask = Task.once 'repository-status-handler', @getPath(), ({statuses, upstream}) => statusesUnchanged = _.isEqual(statuses, @statuses) and _.isEqual(upstream, @upstream)