0
# Signature Handling
1

2
Git signature creation and management for author and committer information. The Signature class handles the creation and formatting of Git signatures used in commits, tags, and other Git objects.
3

4
## Core Imports
5

6
```javascript
7
const NodeGit = require('nodegit');
8
const Signature = NodeGit.Signature;
9
```
10

11
## Capabilities
12

13
### Signature Creation
14

15
Create signatures for various Git operations.
16

17
```javascript { .api }
18
/**
19
 * Create a signature with current timestamp
20
 * @param {String} name - Name of the person
21
 * @param {String} email - Email address
22
 * @returns {Signature} New signature instance
23
 */
24
Signature.now(name, email): Signature;
25

26
/**
27
 * Create a signature with specific timestamp
28
 * @param {String} name - Name of the person
29
 * @param {String} email - Email address
30
 * @param {Number} time - Unix timestamp
31
 * @param {Number} offset - Timezone offset in minutes
32
 * @returns {Signature} New signature instance
33
 */
34
Signature.create(name, email, time, offset): Signature;
35

36
/**
37
 * Create a signature from current Git configuration
38
 * @param {Repository} repo - Repository to get configuration from
39
 * @returns {Promise<Signature>} Signature from repository config
40
 */
41
Signature.default(repo): Promise<Signature>;
42
```
43

44
### Signature Information
45

46
Access signature data and metadata.
47

48
```javascript { .api }
49
/**
50
 * Get the name from the signature
51
 * @returns {String} Person's name
52
 */
53
name(): string;
54

55
/**
56
 * Get the email from the signature
57
 * @returns {String} Person's email address
58
 */
59
email(): string;
60

61
/**
62
 * Get the timestamp when the signature was created
63
 * @returns {Time} Time object with timestamp and offset
64
 */
65
when(): Time;
66
```
67

68
### Signature Formatting
69

70
Convert signatures to string representations.
71

72
```javascript { .api }
73
/**
74
 * Get standard string representation of the signature
75
 * @param {Boolean} withTime - Whether to include timestamp (default: false)
76
 * @returns {String} Formatted signature string
77
 */
78
toString(withTime): string;
79
```
80

81
**Usage Examples:**
82

83
```javascript
84
const NodeGit = require('nodegit');
85

86
// Create signature with current time
87
const author = NodeGit.Signature.now('John Doe', 'john@example.com');
88
console.log(author.toString()); // "John Doe <john@example.com>"
89
console.log(author.toString(true)); // "John Doe <john@example.com> 1609459200 +0000"
90

91
// Create signature with specific time
92
const committer = NodeGit.Signature.create(
93
  'Jane Smith',
94
  'jane@example.com',
95
  1609459200, // Unix timestamp
96
  -480 // PST timezone offset
97
);
98

99
// Get signature from repository configuration
100
NodeGit.Repository.open('./my-repo')
101
  .then(repo => {
102
    return NodeGit.Signature.default(repo);
103
  })
104
  .then(signature => {
105
    console.log(`Default signature: ${signature.name()} <${signature.email()}>`);
106
  });
107

108
// Use signatures in commit creation
109
NodeGit.Repository.open('./my-repo')
110
  .then(repo => {
111
    const author = NodeGit.Signature.now('John Doe', 'john@example.com');
112
    const committer = NodeGit.Signature.now('Jane Smith', 'jane@example.com');
113
    
114
    return repo.createCommitOnHead(
115
      ['modified-file.txt'],
116
      author,
117
      committer,
118
      'Update file with new content'
119
    );
120
  })
121
  .then(commitOid => {
122
    console.log(`Created commit: ${commitOid}`);
123
  });
124

125
// Extract signature information
126
const signature = NodeGit.Signature.now('Alice Johnson', 'alice@example.com');
127
console.log(`Name: ${signature.name()}`);
128
console.log(`Email: ${signature.email()}`);
129

130
const timeInfo = signature.when();
131
console.log(`Timestamp: ${timeInfo.time()}`);
132
console.log(`Timezone offset: ${timeInfo.offset()} minutes`);
133
```
134

135
## Types
136

137
```javascript { .api }
138
interface Time {
139
  /** Get the Unix timestamp */
140
  time(): number;
141
  /** Get the timezone offset in minutes */
142
  offset(): number;
143
  /** Get the timezone sign ('+' or '-') */
144
  sign(): string;
145
}
146
```
147

148
## Common Patterns
149

150
### Repository Default Signature
151

152
```javascript
153
// Get signature from repository config
154
async function getRepoSignature(repo) {
155
  try {
156
    return await NodeGit.Signature.default(repo);
157
  } catch (error) {
158
    // Fallback if no user.name/user.email configured
159
    return NodeGit.Signature.now('Unknown User', 'unknown@example.com');
160
  }
161
}
162
```
163

164
### Signature Validation
165

166
```javascript
167
// Validate signature has required information
168
function validateSignature(signature) {
169
  const name = signature.name();
170
  const email = signature.email();
171
  
172
  if (!name || name.trim().length === 0) {
173
    throw new Error('Signature must have a name');
174
  }
175
  
176
  if (!email || !email.includes('@')) {
177
    throw new Error('Signature must have a valid email');
178
  }
179
  
180
  return true;
181
}
182
```
183

184
### Time Zone Handling
185

186
```javascript
187
// Create signature with specific timezone
188
function createSignatureWithTimezone(name, email, timeZoneOffset) {
189
  const now = Math.floor(Date.now() / 1000);
190
  return NodeGit.Signature.create(name, email, now, timeZoneOffset);
191
}
192

193
// PST is UTC-8 (480 minutes behind)
194
const pstSignature = createSignatureWithTimezone('User', 'user@example.com', -480);
195

196
// EST is UTC-5 (300 minutes behind)  
197
const estSignature = createSignatureWithTimezone('User', 'user@example.com', -300);
198
```