0
# Tildify
1

2
Tildify converts absolute file system paths to tilde notation by replacing the user's home directory with `~`. It provides a lightweight, zero-dependency utility for displaying user-friendly path representations in CLI tools and development utilities.
3

4
## Package Information
5

6
- **Package Name**: tildify
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install tildify`
10
- **Node.js**: ^12.20.0 || ^14.13.1 || >=16.0.0
11

12
## Core Imports
13

14
```javascript
15
import tildify from 'tildify';
16
```
17

18
TypeScript:
19

20
```typescript
21
import tildify from 'tildify';
22
```
23

24
## Basic Usage
25

26
```javascript
27
import tildify from 'tildify';
28

29
// Convert home directory path
30
tildify('/Users/sindresorhus/dev');
31
//=> '~/dev'
32

33
// Home directory itself becomes ~
34
tildify('/Users/sindresorhus');
35
//=> '~'
36

37
// Paths outside home directory remain unchanged
38
tildify('/usr/local/bin');
39
//=> '/usr/local/bin'
40

41
// Relative paths remain unchanged
42
tildify('relative/path');
43
//=> 'relative/path'
44
```
45

46
## Capabilities
47

48
### Path Conversion
49

50
Converts absolute paths to tilde notation when the path starts with the user's home directory.
51

52
```javascript { .api }
53
/**
54
 * Convert an absolute path to a tilde path by replacing the user's home directory with ~
55
 * @param absolutePath - The absolute file system path to convert
56
 * @returns The path with home directory replaced by ~, or original path if not under home directory
57
 */
58
function tildify(absolutePath: string): string;
59
```
60

61
**Parameters:**
62
- `absolutePath` (string): The absolute file system path to convert
63

64
**Returns:**
65
- `string`: The path with the home directory replaced by `~`, or the original path if it doesn't start with the home directory
66

67
**Behavior:**
68
- Normalizes the input path using Node.js `path.normalize()`
69
- Only converts paths that start exactly with the user's home directory (obtained via `os.homedir()`)
70
- Handles cross-platform path separators correctly
71
- Returns relative paths unchanged
72
- Returns paths that contain the home directory in the middle unchanged
73
- Paths like `/home/usernamefoo/file` are NOT converted (must be exactly `/home/username/`)
74

75
**Usage Examples:**
76

77
```javascript
78
import tildify from 'tildify';
79

80
// Basic conversion
81
tildify('/Users/sindresorhus/projects/awesome-project');
82
//=> '~/projects/awesome-project'
83

84
// Home directory edge case
85
tildify('/Users/sindresorhus');
86
//=> '~'
87

88
// Non-home paths remain unchanged  
89
tildify('/usr/local/bin/node');
90
//=> '/usr/local/bin/node'
91

92
// Relative paths remain unchanged
93
tildify('./local/path');
94
//=> './local/path'
95

96
// Similar but not exact home directory paths remain unchanged
97
tildify('/Users/sindresorhusabc/file');
98
//=> '/Users/sindresorhusabc/file'
99
```