mirror of
https://github.com/pulsar-edit/pulsar.git
synced 2024-09-20 23:48:05 +03:00
📝 Use TomDoc style comments in Git class
This commit is contained in:
parent
ed8b8f005f
commit
65ec0a2f0a
118
src/git.coffee
118
src/git.coffee
@ -27,17 +27,19 @@ class Git
|
|||||||
Emitter.includeInto(this)
|
Emitter.includeInto(this)
|
||||||
Subscriber.includeInto(this)
|
Subscriber.includeInto(this)
|
||||||
|
|
||||||
# Private: Creates a new `Git` instance.
|
# Public: Creates a new Git instance.
|
||||||
#
|
#
|
||||||
# * path: The path to the git repository to open
|
# path - The path to the Git repository to open.
|
||||||
# * options:
|
# options - An object with the following keys (default: {}):
|
||||||
# + refreshOnWindowFocus:
|
# :refreshOnWindowFocus - `true` to refresh the index and statuses when the
|
||||||
# A Boolean that identifies if the windows should refresh
|
# window is focused.
|
||||||
|
#
|
||||||
|
# Returns a Git instance or null if the repository could not be opened.
|
||||||
@open: (path, options) ->
|
@open: (path, options) ->
|
||||||
return null unless path
|
return null unless path
|
||||||
try
|
try
|
||||||
new Git(path, options)
|
new Git(path, options)
|
||||||
catch e
|
catch
|
||||||
null
|
null
|
||||||
|
|
||||||
@exists: (path) ->
|
@exists: (path) ->
|
||||||
@ -47,20 +49,6 @@ class Git
|
|||||||
else
|
else
|
||||||
false
|
false
|
||||||
|
|
||||||
path: null
|
|
||||||
statuses: null
|
|
||||||
upstream: null
|
|
||||||
branch: null
|
|
||||||
statusTask: null
|
|
||||||
|
|
||||||
# Private: Creates a new `Git` object.
|
|
||||||
#
|
|
||||||
# * path: The {String} representing the path to your git working directory
|
|
||||||
# * options:
|
|
||||||
# + refreshOnWindowFocus: If `true`, {#refreshIndex} and {#refreshStatus}
|
|
||||||
# are called on focus
|
|
||||||
# + project: A project that supplies buffers that will be monitored for
|
|
||||||
# save and reload events to trigger status refreshes.
|
|
||||||
constructor: (path, options={}) ->
|
constructor: (path, options={}) ->
|
||||||
@repo = GitUtils.open(path)
|
@repo = GitUtils.open(path)
|
||||||
unless @repo?
|
unless @repo?
|
||||||
@ -80,7 +68,7 @@ class Git
|
|||||||
if @project?
|
if @project?
|
||||||
@subscribe @project.eachBuffer (buffer) => @subscribeToBuffer(buffer)
|
@subscribe @project.eachBuffer (buffer) => @subscribeToBuffer(buffer)
|
||||||
|
|
||||||
# Private: Subscribes to buffer events.
|
# Subscribes to buffer events.
|
||||||
subscribeToBuffer: (buffer) ->
|
subscribeToBuffer: (buffer) ->
|
||||||
@subscribe buffer, 'saved reloaded path-changed', =>
|
@subscribe buffer, 'saved reloaded path-changed', =>
|
||||||
if path = buffer.getPath()
|
if path = buffer.getPath()
|
||||||
@ -100,29 +88,29 @@ class Git
|
|||||||
|
|
||||||
@unsubscribe()
|
@unsubscribe()
|
||||||
|
|
||||||
# Private: Returns the corresponding {Repository}
|
# Returns the corresponding {Repository}
|
||||||
getRepo: ->
|
getRepo: ->
|
||||||
unless @repo?
|
unless @repo?
|
||||||
throw new Error("Repository has been destroyed")
|
throw new Error("Repository has been destroyed")
|
||||||
@repo
|
@repo
|
||||||
|
|
||||||
# Public: Reread the index to update any values that have changed since the
|
# Reread the index to update any values that have changed since the
|
||||||
# last time the index was read.
|
# last time the index was read.
|
||||||
refreshIndex: -> @getRepo().refreshIndex()
|
refreshIndex: -> @getRepo().refreshIndex()
|
||||||
|
|
||||||
# Public: Returns the path of the repository.
|
# Public: Returns the {String} path of the repository.
|
||||||
getPath: ->
|
getPath: ->
|
||||||
@path ?= fs.absolute(@getRepo().getPath())
|
@path ?= fs.absolute(@getRepo().getPath())
|
||||||
|
|
||||||
# Public: Returns the working directory of the repository.
|
# Public: Returns the {String} working directory path of the repository.
|
||||||
getWorkingDirectory: -> @getRepo().getWorkingDirectory()
|
getWorkingDirectory: -> @getRepo().getWorkingDirectory()
|
||||||
|
|
||||||
# Public: Returns the status of a single path in the repository.
|
# Public: Get the status of a single path in the repository.
|
||||||
#
|
#
|
||||||
# * path:
|
# path - A {String} repository-relative path.
|
||||||
# A String defining a relative path
|
|
||||||
#
|
#
|
||||||
# Returns a {Number}, FIXME representing what?
|
# Returns a {Number} representing the status. This value can be passed to
|
||||||
|
# {.isStatusModified} or {.isStatusNew} to get more information.
|
||||||
getPathStatus: (path) ->
|
getPathStatus: (path) ->
|
||||||
currentPathStatus = @statuses[path] ? 0
|
currentPathStatus = @statuses[path] ? 0
|
||||||
pathStatus = @getRepo().getStatus(@relativize(path)) ? 0
|
pathStatus = @getRepo().getStatus(@relativize(path)) ? 0
|
||||||
@ -134,7 +122,9 @@ class Git
|
|||||||
@emit 'status-changed', path, pathStatus
|
@emit 'status-changed', path, pathStatus
|
||||||
pathStatus
|
pathStatus
|
||||||
|
|
||||||
# Public: Returns true if the given path is ignored.
|
# Public: Is the given path ignored?
|
||||||
|
#
|
||||||
|
# Returns a {Boolean}.
|
||||||
isPathIgnored: (path) -> @getRepo().isIgnored(@relativize(path))
|
isPathIgnored: (path) -> @getRepo().isIgnored(@relativize(path))
|
||||||
|
|
||||||
# Public: Returns true if the given status indicates modification.
|
# Public: Returns true if the given status indicates modification.
|
||||||
@ -163,22 +153,22 @@ class Git
|
|||||||
# `refs/remotes`. It also shortens the SHA-1 of a detached `HEAD` to 7
|
# `refs/remotes`. It also shortens the SHA-1 of a detached `HEAD` to 7
|
||||||
# characters.
|
# characters.
|
||||||
#
|
#
|
||||||
# Returns a String.
|
# Returns a {String}.
|
||||||
getShortHead: -> @getRepo().getShortHead()
|
getShortHead: -> @getRepo().getShortHead()
|
||||||
|
|
||||||
# Public: Restore the contents of a path in the working directory and index
|
# Public: Restore the contents of a path in the working directory and index
|
||||||
# to the version at `HEAD`.
|
# to the version at `HEAD`.
|
||||||
#
|
#
|
||||||
# This is essentially the same as running:
|
# This is essentially the same as running:
|
||||||
|
#
|
||||||
# ```
|
# ```
|
||||||
# git reset HEAD -- <path>
|
# git reset HEAD -- <path>
|
||||||
# git checkout HEAD -- <path>
|
# git checkout HEAD -- <path>
|
||||||
# ```
|
# ```
|
||||||
#
|
#
|
||||||
# * path:
|
# path - The {String} path to checkout.
|
||||||
# The String path to checkout
|
|
||||||
#
|
#
|
||||||
# Returns a Boolean that's true if the method was successful.
|
# Returns a {Boolean} that's true if the method was successful.
|
||||||
checkoutHead: (path) ->
|
checkoutHead: (path) ->
|
||||||
headCheckedOut = @getRepo().checkoutHead(@relativize(path))
|
headCheckedOut = @getRepo().checkoutHead(@relativize(path))
|
||||||
@getPathStatus(path) if headCheckedOut
|
@getPathStatus(path) if headCheckedOut
|
||||||
@ -186,10 +176,9 @@ class Git
|
|||||||
|
|
||||||
# Public: Checks out a branch in your repository.
|
# Public: Checks out a branch in your repository.
|
||||||
#
|
#
|
||||||
# * reference:
|
# reference - The String reference to checkout
|
||||||
# The String reference to checkout
|
# create - A Boolean value which, if true creates the new reference if it
|
||||||
# * create:
|
# doesn't exist.
|
||||||
# A Boolean value which, if true creates the new reference if it doesn't exist.
|
|
||||||
#
|
#
|
||||||
# Returns a Boolean that's true if the method was successful.
|
# Returns a Boolean that's true if the method was successful.
|
||||||
checkoutReference: (reference, create) ->
|
checkoutReference: (reference, create) ->
|
||||||
@ -200,27 +189,26 @@ class Git
|
|||||||
# This compares the working directory contents of the path to the `HEAD`
|
# This compares the working directory contents of the path to the `HEAD`
|
||||||
# version.
|
# version.
|
||||||
#
|
#
|
||||||
# * path:
|
# path - The {String} path to check.
|
||||||
# The String path to check
|
|
||||||
#
|
#
|
||||||
# Returns an object with two keys, `added` and `deleted`. These will always
|
# Returns an {Object} with the following keys:
|
||||||
# be greater than 0.
|
# :added - The {Number} of added lines.
|
||||||
|
# :deleted - The {Number} of deleted lines.
|
||||||
getDiffStats: (path) -> @getRepo().getDiffStats(@relativize(path))
|
getDiffStats: (path) -> @getRepo().getDiffStats(@relativize(path))
|
||||||
|
|
||||||
# Public: Identifies if a path is a submodule.
|
# Public: Is the given path a submodule in the repository?
|
||||||
#
|
#
|
||||||
# * path:
|
# path - The {String} path to check.
|
||||||
# The String path to check
|
|
||||||
#
|
#
|
||||||
# Returns a Boolean.
|
# Returns a {Boolean}.
|
||||||
isSubmodule: (path) -> @getRepo().isSubmodule(@relativize(path))
|
isSubmodule: (path) -> @getRepo().isSubmodule(@relativize(path))
|
||||||
|
|
||||||
# Public: Retrieves the status of a directory.
|
# Public: Get the status of a directory in the repository's working directory.
|
||||||
#
|
#
|
||||||
# * path:
|
# path - The {String} path to check.
|
||||||
# The String path to check
|
|
||||||
#
|
#
|
||||||
# Returns a Number representing the status.
|
# Returns a {Number} representing the status. This value can be passed to
|
||||||
|
# {.isStatusModified} or {.isStatusNew} to get more information.
|
||||||
getDirectoryStatus: (directoryPath) ->
|
getDirectoryStatus: (directoryPath) ->
|
||||||
{sep} = require 'path'
|
{sep} = require 'path'
|
||||||
directoryPath = "#{directoryPath}#{sep}"
|
directoryPath = "#{directoryPath}#{sep}"
|
||||||
@ -232,16 +220,14 @@ class Git
|
|||||||
# Public: Retrieves the line diffs comparing the `HEAD` version of the given
|
# Public: Retrieves the line diffs comparing the `HEAD` version of the given
|
||||||
# path and the given text.
|
# path and the given text.
|
||||||
#
|
#
|
||||||
# This is similar to the commit numbers reported by `git status` when a
|
# path - The {String} path relative to the repository.
|
||||||
# remote tracking branch exists.
|
# text - The {String} to compare against the `HEAD` contents
|
||||||
#
|
#
|
||||||
# * path:
|
# Returns an {Array} of hunk {Object}s with the following keys:
|
||||||
# The String path (relative to the repository)
|
# :oldStart - The line {Number} of the old hunk.
|
||||||
# * text:
|
# :newStart - The line {Number} of the new hunk.
|
||||||
# The String to compare against the `HEAD` contents
|
# :oldLines - The {Number} of lines in the old hunk.
|
||||||
#
|
# :newLines - The {Number} of lines in the new hunk
|
||||||
# Returns an object with two keys, `ahead` and `behind`. These will always be
|
|
||||||
# greater than zero.
|
|
||||||
getLineDiffs: (path, text) ->
|
getLineDiffs: (path, text) ->
|
||||||
# Ignore eol of line differences on windows so that files checked in as
|
# Ignore eol of line differences on windows so that files checked in as
|
||||||
# LF don't report every line modified when the text contains CRLF endings.
|
# LF don't report every line modified when the text contains CRLF endings.
|
||||||
@ -257,7 +243,7 @@ class Git
|
|||||||
# Public: Returns the upstream branch for the current HEAD, or null if there
|
# Public: Returns the upstream branch for the current HEAD, or null if there
|
||||||
# is no upstream branch for the current HEAD.
|
# is no upstream branch for the current HEAD.
|
||||||
#
|
#
|
||||||
# Returns a String branch name such as `refs/remotes/origin/master`
|
# Returns a {String} branch name such as `refs/remotes/origin/master`.
|
||||||
getUpstreamBranch: -> @getRepo().getUpstreamBranch()
|
getUpstreamBranch: -> @getRepo().getUpstreamBranch()
|
||||||
|
|
||||||
# Public: Returns the current SHA for the given reference.
|
# Public: Returns the current SHA for the given reference.
|
||||||
@ -265,19 +251,21 @@ class Git
|
|||||||
|
|
||||||
# Public: Gets all the local and remote references.
|
# Public: Gets all the local and remote references.
|
||||||
#
|
#
|
||||||
# Returns an object with three keys: `heads`, `remotes`, and `tags`. Each key
|
# Returns an {Object} with the following keys:
|
||||||
# can be an array of strings containing the reference names.
|
# :heads - An {Array} of head reference names.
|
||||||
|
# :remotes - An {Array} of remote reference names.
|
||||||
|
# :tags - An {Array} of tag reference names.
|
||||||
getReferences: -> @getRepo().getReferences()
|
getReferences: -> @getRepo().getReferences()
|
||||||
|
|
||||||
# Public: Returns the number of commits behind the current branch is from the
|
# Public: Returns the number of commits behind the current branch is from the
|
||||||
# default remote branch.
|
# its upstream remote branch.
|
||||||
getAheadBehindCount: (reference) -> @getRepo().getAheadBehindCount(reference)
|
getAheadBehindCount: (reference) -> @getRepo().getAheadBehindCount(reference)
|
||||||
|
|
||||||
# Public: Returns true if the given branch exists.
|
# Public: Returns true if the given branch exists.
|
||||||
hasBranch: (branch) -> @getReferenceTarget("refs/heads/#{branch}")?
|
hasBranch: (branch) -> @getReferenceTarget("refs/heads/#{branch}")?
|
||||||
|
|
||||||
# Private: Refreshes the current git status in an outside process and
|
# Refreshes the current git status in an outside process and asynchronously
|
||||||
# asynchronously updates the relevant properties.
|
# updates the relevant properties.
|
||||||
refreshStatus: ->
|
refreshStatus: ->
|
||||||
@statusTask = Task.once require.resolve('./repository-status-handler'), @getPath(), ({statuses, upstream, branch}) =>
|
@statusTask = Task.once require.resolve('./repository-status-handler'), @getPath(), ({statuses, upstream, branch}) =>
|
||||||
statusesUnchanged = _.isEqual(statuses, @statuses) and _.isEqual(upstream, @upstream) and _.isEqual(branch, @branch)
|
statusesUnchanged = _.isEqual(statuses, @statuses) and _.isEqual(upstream, @upstream) and _.isEqual(branch, @branch)
|
||||||
|
Loading…
Reference in New Issue
Block a user