Skip to content

Commit cf62af8

Browse files
sjzarsjzar
authored
add document (#15)
1 parent 79e28e4 commit cf62af8

30 files changed

+2060
-106
lines changed

‎README.md‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,21 @@ ips 是一个命令行工具与库，可以轻松完成 IP 地理位置数据库
1717
go install github.com/sjzar/ips@latest
1818
```
1919

20+
#### 二进制安装
21+
22+
[![Windows](https://img.shields.io/badge/-Windows_x64-blue.svg?style=for-the-badge&logo=windows)](https://github.com/sjzar/ips/releases/latest/download/ips_windows.exe)
23+
[![Unix](https://img.shields.io/badge/-Linux/BSD-red.svg?style=for-the-badge&logo=linux)](https://github.com/sjzar/ips/releases/latest/download/ips_linux)
24+
[![MacOS](https://img.shields.io/badge/-MacOS-lightblue.svg?style=for-the-badge&logo=apple)](https://github.com/sjzar/ips/releases/latest/download/ips_macos)
25+
26+
从 [GitHub Releases](https://github.com/sjzar/ips/releases) 下载最新版本的二进制文件。
27+
28+
#### Homebrew 安装
29+
30+
```bash
31+
brew tap sjzar/tap
32+
brew install ips
33+
```
34+
2035
### 特性
2136

2237
* 一键查询、转存和打包 IP 地理位置数据库
@@ -30,7 +45,7 @@ go install github.com/sjzar/ips@latest
3045

3146
| 数据库 | 查询 | 转存 | 打包 | 官方网站 | 说明 |
3247
|:----------|:---|:---|:---|:--------------------------------------------------|:----------|
33-
| txt | - | ✅ | ✅ | - | 本项目转存时使用 |
48+
| txt | ✅ | ✅ | ✅ | - | 本项目转存时使用 |
3449
| ipdb | ✅ | ✅ | ✅ | [Link](https://ipip.net) | |
3550
| mmdb | ✅ | ✅ | ✅ | [Link](https://maxmind.com) | |
3651
| awdb | ✅ | ✅ | - | [Link](https://ipplus360.com) | |
@@ -40,6 +55,8 @@ go install github.com/sjzar/ips@latest
4055

4156
### 使用方法
4257

58+
更详细的使用说明请翻阅 [usage.md](./docs/usage.md) 。
59+
4360
#### 查询
4461

4562
```shell

‎README_en.md‎

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,21 @@ ips is a command-line tool and library that facilitates the querying, dumping, a
1717
go install github.com/sjzar/ips@latest
1818
```
1919

20+
#### Binary Installation
21+
22+
[![Windows](https://img.shields.io/badge/-Windows_x64-blue.svg?style=for-the-badge&logo=windows)](https://github.com/sjzar/ips/releases/latest/download/ips_windows.exe)
23+
[![Unix](https://img.shields.io/badge/-Linux/BSD-red.svg?style=for-the-badge&logo=linux)](https://github.com/sjzar/ips/releases/latest/download/ips_linux)
24+
[![MacOS](https://img.shields.io/badge/-MacOS-lightblue.svg?style=for-the-badge&logo=apple)](https://github.com/sjzar/ips/releases/latest/download/ips_macos)
25+
26+
Download the latest binary files from [GitHub Releases](https://github.com/sjzar/ips/releases).
27+
28+
#### Homebrew Installation
29+
30+
```shell
31+
brew tap sjzar/tap
32+
brew install ips
33+
```
34+
2035
### Features
2136

2237
* One-click querying, dumping, and packaging of IP geolocation databases
@@ -28,18 +43,20 @@ go install github.com/sjzar/ips@latest
2843

2944
### Supported Databases
3045

31-
| Database | Query | Dump | Pack | Official Website | Command |
32-
|:----------|:---|:---|:---|:--------------------------------------------------|:----------|
33-
| txt | - | ✅ | ✅ | - | Used for project dumps |
34-
| ipdb | ✅ | ✅ | ✅ | [Link](https://ipip.net) | |
35-
| mmdb | ✅ | ✅ | ✅ | [Link](https://maxmind.com) | |
36-
| awdb | ✅ | ✅ | - | [Link](https://ipplus360.com) | |
37-
| qqwry | ✅ | ✅ | - | [Link](https://cz88.net) | IPv4 only |
38-
| zxinc | ✅ | ✅ | - | [Link](https://ip.zxinc.org) | IPv6 only |
39-
| ip2region | ✅ | ✅ | - | [Link](https://github.com/lionsoul2014/ip2region) | IPv4 only |
46+
| Database | Query | Dump | Pack | Official Website | Command |
47+
|:----------|:------|:-----|:-----|:--------------------------------------------------|:-----------------------|
48+
| txt | ✅ | ✅ | ✅ | - | Used for project dumps |
49+
| ipdb | ✅ | ✅ | ✅ | [Link](https://ipip.net) | |
50+
| mmdb | ✅ | ✅ | ✅ | [Link](https://maxmind.com) | |
51+
| awdb | ✅ | ✅ | - | [Link](https://ipplus360.com) | |
52+
| qqwry | ✅ | ✅ | - | [Link](https://cz88.net) | IPv4 only |
53+
| zxinc | ✅ | ✅ | - | [Link](https://ip.zxinc.org) | IPv6 only |
54+
| ip2region | ✅ | ✅ | - | [Link](https://github.com/lionsoul2014/ip2region) | IPv4 only |
4055

4156
### Usage
4257

58+
For more detailed usage instructions, please refer to [usage_en.md](./docs/usage_en.md).
59+
4360
#### Query
4461

4562
```shell

‎cmd/ips/cmd_config.go‎

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -37,26 +37,31 @@ func init() {
3737

3838
var configCmd = &cobra.Command{
3939
Use: "config [set <key> <value>] [unset <key>] [reset]",
40-
Short: "View or modify ips configuration items",
41-
Long: `Example:
42-
# set ipv4 database file path
43-
ips config set ipv4 ~/path/to/ipv4.db
40+
Short: "Manage IPS configuration settings",
41+
Long: `The 'ips config' command allows you to view and change various settings for IPS.
4442
45-
# set ipv4 database format
46-
ips config set ipv4_format ipdb
43+
You can specify database file paths, select output fields, and choose the format for IP databases.
4744
48-
# set query fields
49-
ips config set fields "country,province,city,isp"
45+
Use 'set' to change a setting, 'unset' to remove it, and 'reset' to revert all settings to default values.
5046
51-
# unset ipv6 database file path
52-
ips config unset ipv6
47+
For IPv6, use similar commands, like 'ips config set ipv6_format mmdb' to specify the format.
5348
54-
# reset config
55-
ips config reset
49+
For more detailed information and advanced configuration options, please refer to https://github.com/sjzar/ips/blob/main/docs/config.md
50+
`,
51+
Example: ` # Set the IPv4 database file path:
52+
ips config set ipv4 ~/path/to/ipv4.db
5653
57-
# ipv4 format: ipip, qqwry, maxmind, ip2region, dbip
58-
# ipv6 format: zxinc, maxmind, dbip
59-
# use 'ips config set ipv4 ipdb' or 'ips config set ipv6 zxinc' to set format`,
54+
# Set the IPv4 database format:
55+
ips config set ipv4_format ipdb
56+
57+
# Configure the fields to display in query results:
58+
ips config set fields "country,province,city,isp"
59+
60+
# Remove the IPv6 database file path setting:
61+
ips config unset ipv6
62+
63+
# Reset all configuration settings to their default values:
64+
ips config reset`,
6065
PreRun: PreRunInit,
6166
Run: Config,
6267
}

‎cmd/ips/cmd_download.go‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -31,17 +31,20 @@ func init() {
3131
}
3232

3333
var downloadCmd = &cobra.Command{
34-
Use: "download [file] [url]",
35-
Short: "Download database files",
36-
Long: `Example:
37-
# download list file city.free.ipdb
38-
ips download city.free.ipdb
34+
Use: "download [database_name] [custom_url]",
35+
Short: "Download IP database files",
36+
Long: `The 'ips download' command facilitates the acquisition and updating of IP geolocation database files.
3937
40-
# download another database file
41-
ips download city.ipdb https://foo.com/city.ipdb
38+
For more detailed information and advanced configuration options, please refer to https://github.com/sjzar/ips/blob/main/docs/download.md
39+
`,
40+
Example: ` # To download a predefined database file
41+
ips download city.free.ipdb
4242
43-
# set database file after download
44-
ips config set ipv4 city.ipdb`,
43+
# To download a database file from a custom URL
44+
ips download city.ipdb https://foo.com/city.ipdb
45+
46+
# To configure the downloaded file as the default IPv4 database
47+
ips config set ipv4 city.ipdb`,
4548
PreRun: PreRunInit,
4649
Run: Download,
4750
}

‎cmd/ips/cmd_dump.go‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -27,26 +27,30 @@ func init() {
2727
rootCmd.AddCommand(dumpCmd)
2828

2929
// operate
30-
dumpCmd.Flags().StringVarP(&dpFields, "fields", "f", "", "Specify the fields to be dumped from the input file. Default is all fields.")
31-
dumpCmd.Flags().StringVarP(&dpRewriterFiles, "rewrite-files", "r", "", "List of files that need to be rewritten based on the given configurations.")
32-
dumpCmd.Flags().StringVarP(&lang, "lang", "", "", "Set the language for the output. Example values: en, zh-CN, etc.")
30+
dumpCmd.Flags().StringVarP(&dpFields, "fields", "f", "", UsageDPFields)
31+
dumpCmd.Flags().StringVarP(&dpRewriterFiles, "rewrite-files", "r", "", UsageRewriteFiles)
32+
dumpCmd.Flags().StringVarP(&lang, "lang", "", "", UsageLang)
3333

3434
// input & output
35-
dumpCmd.Flags().StringVarP(&inputFile, "input-file", "i", "", "Path to the IP database file.")
36-
dumpCmd.Flags().StringVarP(&inputFormat, "input-format", "", "", "Specify the format of the input file. Examples: ipdb, mmdb, etc.")
37-
dumpCmd.Flags().StringVarP(&readerOption, "input-option", "", "", "Specify the option for database reader.")
38-
dumpCmd.Flags().StringVarP(&outputFile, "output-file", "o", "", "Path to the dumped file.")
35+
dumpCmd.Flags().StringVarP(&inputFile, "input-file", "i", "", UsageDPInputFile)
36+
dumpCmd.Flags().StringVarP(&inputFormat, "input-format", "", "", UsageDPInputFormat)
37+
dumpCmd.Flags().StringVarP(&readerOption, "input-option", "", "", UsageReaderOption)
38+
dumpCmd.Flags().StringVarP(&outputFile, "output-file", "o", "", UsageDumpOutputFile)
3939

4040
}
4141

4242
var dumpCmd = &cobra.Command{
4343
Use: "dump -i inputFile [--input-format] [-o outputFile]",
44-
Short: "Dump data from IP database file to plain file.",
45-
Long: `Dump data from IP database file to plain file.
44+
Short: "Export IP database contents to a text file",
45+
Long: `Use the 'ips dump' command to extract and export data from IP databases into a plain text format, which can be tailored by specifying fields, formats, and languages.
4646
47-
Example:
48-
ips dump -i geoip.mmdb -o geoip.txt
47+
For more detailed information and advanced configuration options, please refer to https://github.com/sjzar/ips/blob/main/docs/dump.md
4948
`,
49+
Example: ` # Export all fields from an IP database file to a text file
50+
ips dump -i geoip.mmdb -o geoip.txt
51+
52+
# Export specific fields (country and city) from an IP database file
53+
ips dump -i geoip.mmdb -o geoip.txt --fields "country,city"`,
5054
PreRun: PreRunInit,
5155
Run: Dump,
5256
}

‎cmd/ips/cmd_myip.go‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -31,32 +31,32 @@ func init() {
3131
myipCmd.Flags().IntVarP(&myIPTimeoutS, "timeout", "", 0, "Set the maximum wait time for detectors.")
3232

3333
// operate
34-
myipCmd.Flags().StringVarP(&fields, "fields", "f", "", "Specify the fields of interest for the IP data. Separate multiple fields with commas.")
35-
myipCmd.Flags().BoolVarP(&useDBFields, "use-db-fields", "", false, "Use field names as they appear in the database. Default is common field names.")
36-
myipCmd.Flags().StringVarP(&rewriteFiles, "rewrite-files", "r", "", "List of files that need to be rewritten based on the given configurations.")
37-
myipCmd.Flags().StringVarP(&lang, "lang", "", "", "Set the language for the output. Example values: en, zh-CN, etc.")
34+
myipCmd.Flags().StringVarP(&fields, "fields", "f", "", UsageFields)
35+
myipCmd.Flags().BoolVarP(&useDBFields, "use-db-fields", "", false, UsageUseDBFields)
36+
myipCmd.Flags().StringVarP(&rewriteFiles, "rewrite-files", "r", "", UsageRewriteFiles)
37+
myipCmd.Flags().StringVarP(&lang, "lang", "", "", UsageLang)
3838

3939
// database
40-
myipCmd.Flags().StringVarP(&rootFile, "file", "i", "", "Path to the IPv4 and IPv6 database file.")
41-
myipCmd.Flags().StringVarP(&rootFormat, "format", "", "", "Specify the format of the database. Examples: ipdb, mmdb, etc.")
42-
myipCmd.Flags().StringVarP(&rootIPv4File, "ipv4-file", "", "", "Path to the IPv4 database file.")
43-
myipCmd.Flags().StringVarP(&rootIPv4Format, "ipv4-format", "", "", "Specify the format for IPv4 data. Examples: ipdb, mmdb, etc.")
44-
myipCmd.Flags().StringVarP(&rootIPv6File, "ipv6-file", "", "", "Path to the IPv6 database file.")
45-
myipCmd.Flags().StringVarP(&rootIPv6Format, "ipv6-format", "", "", "Specify the format for IPv6 data. Examples: ipdb, mmdb, etc.")
46-
myipCmd.Flags().StringVarP(&readerOption, "database-option", "", "", "Specify the option for database reader.")
40+
myipCmd.Flags().StringVarP(&rootFile, "file", "i", "", UsageQueryFile)
41+
myipCmd.Flags().StringVarP(&rootFormat, "format", "", "", UsageQueryFormat)
42+
myipCmd.Flags().StringVarP(&rootIPv4File, "ipv4-file", "", "", UsageQueryIPv4File)
43+
myipCmd.Flags().StringVarP(&rootIPv4Format, "ipv4-format", "", "", UsageQueryIPv4Format)
44+
myipCmd.Flags().StringVarP(&rootIPv6File, "ipv6-file", "", "", UsageQueryIPv6File)
45+
myipCmd.Flags().StringVarP(&rootIPv6Format, "ipv6-format", "", "", UsageQueryIPv6Format)
46+
myipCmd.Flags().StringVarP(&readerOption, "database-option", "", "", UsageReaderOption)
4747

4848
// output
49-
myipCmd.Flags().StringVarP(&rootTextFormat, "text-format", "", "", "Specify the desired format for text output. It supports %origin and %values parameters.")
50-
myipCmd.Flags().StringVarP(&rootTextValuesSep, "text-values-sep", "", "", "Specify the separator for values in text output. (default is space)")
51-
myipCmd.Flags().BoolVarP(&rootJson, "json", "j", false, "Output the results in JSON format.")
52-
myipCmd.Flags().BoolVarP(&rootJsonIndent, "json-indent", "", false, "Output the results in indent JSON format.")
53-
myipCmd.Flags().BoolVarP(&rootAlfred, "alfred", "", false, "Output the results in Alfred format.")
49+
myipCmd.Flags().StringVarP(&rootTextFormat, "text-format", "", "", UsageTextFormat)
50+
myipCmd.Flags().StringVarP(&rootTextValuesSep, "text-values-sep", "", "", UsageTextValuesSep)
51+
myipCmd.Flags().BoolVarP(&rootJson, "json", "j", false, UsageJson)
52+
myipCmd.Flags().BoolVarP(&rootJsonIndent, "json-indent", "", false, UsageJsonIndent)
53+
myipCmd.Flags().BoolVarP(&rootAlfred, "alfred", "", false, UsageAlfred)
5454

5555
}
5656

5757
var myipCmd = &cobra.Command{
5858
Use: "myip",
59-
Short: "Retrieve your public IP address.",
59+
Short: "Retrieve your public IP address",
6060
Long: `The 'myip' command uses multiple detectors to discover and return your public IP address.
6161
It is designed to work in scenarios with multiple network interfaces and allows you to specify
6262
the local address for outbound connections, the number of detectors to confirm the IP, and the timeout

‎cmd/ips/cmd_pack.go‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -25,28 +25,29 @@ func init() {
2525
rootCmd.AddCommand(packCmd)
2626

2727
// operate
28-
packCmd.Flags().StringVarP(&dpFields, "fields", "f", "", "Specify the fields to be dumped from the input file. Default is all fields.")
29-
packCmd.Flags().StringVarP(&dpRewriterFiles, "rewrite-files", "r", "", "List of files that need to be rewritten based on the given configurations.")
30-
packCmd.Flags().StringVarP(&lang, "lang", "", "", "Set the language for the output. Example values: en, zh-CN, etc.")
28+
packCmd.Flags().StringVarP(&dpFields, "fields", "f", "", UsageDPFields)
29+
packCmd.Flags().StringVarP(&dpRewriterFiles, "rewrite-files", "r", "", UsageRewriteFiles)
30+
packCmd.Flags().StringVarP(&lang, "lang", "", "", UsageLang)
3131

3232
// input & output
33-
packCmd.Flags().StringVarP(&inputFile, "input-file", "i", "", "Path to the IP database file.")
34-
packCmd.Flags().StringVarP(&inputFormat, "input-format", "", "", "Specify the format of the input file. Examples: ipdb, mmdb, etc.")
35-
packCmd.Flags().StringVarP(&readerOption, "input-option", "", "", "Specify the option for database reader.")
36-
packCmd.Flags().StringVarP(&outputFile, "output-file", "o", "", "Path to the packed IP database file.")
37-
packCmd.Flags().StringVarP(&outputFormat, "output-format", "", "", "Specify the format of the output file. Examples: ipdb, mmdb, etc.")
38-
packCmd.Flags().StringVarP(&writerOption, "output-option", "", "", "Specify the option for database writer.")
33+
packCmd.Flags().StringVarP(&inputFile, "input-file", "i", "", UsageDPInputFile)
34+
packCmd.Flags().StringVarP(&inputFormat, "input-format", "", "", UsageDPInputFormat)
35+
packCmd.Flags().StringVarP(&readerOption, "input-option", "", "", UsageReaderOption)
36+
packCmd.Flags().StringVarP(&outputFile, "output-file", "o", "", UsagePackOutputFile)
37+
packCmd.Flags().StringVarP(&outputFormat, "output-format", "", "", UsagePackOutputFormat)
38+
packCmd.Flags().StringVarP(&writerOption, "output-option", "", "", UsageWriterOption)
3939

4040
}
4141

4242
var packCmd = &cobra.Command{
4343
Use: "pack -i inputFile [--input-format format] -o outputFile [--output-format format]",
44-
Short: "Pack data from IP database file to another IP database file.",
45-
Long: `Pack data from IP database file to another IP database file.
44+
Short: "Repackage IP database file",
45+
Long: `The 'ips pack' command enables users to create a new IP database file from an existing one while allowing for customization of the data fields included.
4646
47-
Example:
48-
ips pack -i geoip.mmdb -o geoip.ipdb
47+
For more detailed information and advanced configuration options, please refer to https://github.com/sjzar/ips/blob/main/docs/pack.md
4948
`,
49+
Example: ` # Package IP Database and Specify Fields
50+
ips pack -i geoip.mmdb -o geoip_custom.ipdb --fields "country,city"`,
5051
PreRun: PreRunInit,
5152
Run: Pack,
5253
}

0 commit comments

Comments
 (0)